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Read This First 


This preface summarizes the chapters, lists related documentation, and describes the style 
and symbol conventions used in this manual. 


How This Manual Is Organized 


This document contains the following chapters: 


Chapter 1 

Chapter 2 

Chapter 3 

Chapter 4 

Chapter 5 
Chapter 6 

Chapter 7 

Chapter 8 

Chapter 9 


Introduction and Installation 

Provides an overview of the assembly language development tools, a 
walkthrough, and installation information. 

Introduction to Common Object File Format 

Discusses the basic COFF concept of sections and how they can help you 
use the assembler and linker more efficiently. Common object file format, or 
COFF, is the object file format used by the MSP430 family tools. Read 
Chapter before using the assembler and linker. 

Assembler Description 

Tells you how to invoke the assembler and discusses source statement 
format, valid constants and expressions, and assembler output. 

Assembler Directives 

Divided into two parts: the first part describes the directives according to 
function, and the second part presents the directives in alphabetical order. 

Instruction Set Summary 

Summarizes the MSP430 instruction set alphabetically. 

Macro Language 

Describes macro directives, substitution symbols used as macro para¬ 
meters, and how to create macros. 

Archiver Description 

Contains instructions for invoking the archiver, creating new archive 
libraries, and modifying existing libraries. 

Linker Description 

Tells you how to Invoke the linker, provides details about linker operation, 
discusses linker directives, and presents a detailed linking example. 

Absolute Lister Description 

Tells you how to invoke the absolute lister so that you can obtain a listing of 
the absolute addresses of an object file. 
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Chapter 10 

Object Format Converter Description 

Tells you how to invoke the object format converter so that you can convert 
a COFF object file into an Intel, Tektronix, or Tl-tagged object format. 

Appendix A 

Common Object File Format 

Contains supplemental technical data about the internal format and 
structure of COFF object files. 

Appendix B 

Symbolic Debugging Directives 

Lists symbolic debugging directives that a high level language can use. 

Appendix C 

Assembler Error Messages 

Lists the assembler error messages. 

Appendix D 

Linker Error Messages 

Lists the linker error messages. 

Appendix E 

ASCII Character Set 

Provides a table of the ASCII character set. 

Appendix F 

Glossary 

Contains a glossary of terms and acronyms used in this book. 

Appendix G 

Floating Point Formats 

Contains informations about the internal format of floating point constants. 


Related Documentation 

The following l\/ISP430 documents are also available. 

The MSP430 Family Data Manual (literature number SPNSxxx) discusses hardware 
aspects of the MSP430, such as pin functions, architecture, stack operation, and inter¬ 
faces, and contains the MSP430 instruction set. 

The MSP430 data sheets contain the recommended operating conditions, electrical 
specifications, and timing characteristics of the MSP430 family devices. 

• MSP430C201 16-Bit Microcontroller Data Sheet (literature number SPNSxxx) 



Read This First 


MSP430 Famil 


Style and Symbol Conventions 

This document uses the following conventions: 

• Program listings, program examples, and interactive displays are shown in a special font. 
Examples use a bold version of the special font for emphasis. Here is a sample program 
listing: 


1 0000 

25 

1 

.p\|/T8 

45 

2 0001 

2(1) 

V 

.p\|/T£ 

47 

3 0002 

4 0003 

32 


.p\|/T£ 

.T£4t: 

50 


• In syntax descriptions, the instruction, command, or directive is in a bold face font and 
parameters are in italics. Portions of a syntax that are in bold face should be entered as 
shown; portions of a syntax that are in italics describe the type of information that should 
be entered. Here is an example of a directive syntax: 

.space size 

.space is the directive. This directive has one parameter, indicated by size. When you 
use .space, the first and only parameter must be the size. 

• Square brackets ( [ and ] ) Identify an optional parameter. If you use an optional 
parameter, you specify the information within the brackets; you don't enter the brackets 
themselves. This is an example of an instruction that has an optional parameter: 

.text [ address ] 

• Braces ({ and }) indicate a list. The symbol I (read as oi) separates items within the list. 
Here's an example of a list: 

{ a 1 b 1 c } 

This provides three choices: a, b, or c. 

• Some directives can have a varying number of parameters. For example, the .byte 
directive can have up to 100 parameters. The syntax for this directive is: 

.byte value-f [,..., valuen\ 

This syntax shows that .byte must have at least one value parameter, but you have the 
option of supplying additional value parameters, separated by commas. 
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Following are other symbols and abbreviations used throughout this document. 


Symbol 

Definition 

Symbol 

Definition 

R0-R3 

Registers with special functions 

R4-R15 

Working registers, general 
purpose 

PC 

Program counter register 

SP 

Stack pointer register 

SR 

Status register 

CG1,CG2 

Constant generator registers 

LSB 

Least significant bit 

MSB 

Most significant bit 

H,h 

Suffix - hexadecimal number 

B,b 

Suffix - binary integer 

Q.q 

Suffix - octal integer 



{ } 

List of parameters 

[ ] 

Optional parameter 

text 

Indicates a “fill in the blank" - replace the text in italics with an appropriate 
substitute. For example, substitute an actual label for label; substitute an actual 
destination expression for expression. 


Trademarks 

IBM, IBM PC, IBM PC/XT, PC-DOS, IBM OS/2, and PS/2 are trademarks of International Business 
Machines Corp. 

MS, MS OS/2, MS-DOS, and MS-Windows are registered trademarks of Microsoft Corp. 

Sun-3, Sun-4, SunView, SunWindows, and Sun Workstation are trademarks of Sun Microsystems, 
Inc. 

UNIX is a registered trademark of AT&T Bell Laboratories, Inc. 

VAX and VMS are trademarks of Digital Equipment Corp. 
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1 Introduction and Installation 

The MSP430 devices are well supported by a full set of hardware and software development 
tools. This document discusses the software development tools included with the MSP430 
assembly language package: 

• Assembler 

• Archiver 

• Linker 

• Absolute Lister 

• ROM Utility 


These tools can be installed on the following systems: 

. PC/AT with PC-DOS, MS-DOS, OS/2 or MS-Windows 

The MSP430 assembly language tools create and use object files that are in common object 
file format (COFF) to facilitate modular programming. Object files contain separate blocks 
(called sections) of code and data that you can load into different MSP430 memory spaces. 
You will be able to program the MSP430 more efficiently if you have a basic understanding 
of COFF. 


1-3 
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1.1 Development Tools Overview 

The figure shows the assembly language development flow. The shaded portion highlights 
the most common development path; the other portions are optional. 



Figure 1.1: MSP430 Assembly Language Development Flow 
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• The assembler translates assembly language source files into machine language object 
files. Source files can contain instructions, assembler directives, and macro directives. 
You can use assembler directives to control various aspects of the assembly process, 
such as the source listing format, symbol definition, and section content. 

• The archiver allows you to collect a group of files into a single archive file. For example, 
you can collect several macros together into a macro library. The assembler will search 
through the library and use only the members that are called as macros by the source 
file. You can also use the archiver to collect a group of object files into an object library. 
The linker will include in the library the members that resolve external references during 
the link. 

• The linker combines object files into a single executable object module. As it creates the 
executable module, it performs relocation and resolves external references. The linker 
accepts relocatable COFF object files (created by the assembler) as input. It also accepts 
archiver library members and output modules created by a previous linker run. Linker 
directives allow you to combine object file sections, bind sections or symbols to 
addresses or within memory ranges, and define or redefine global symbols. 

• The absolute lister provides a file that can be reassembled to produce a listing of the 
absolute addresses of an object file. 

• The MSP430 microcontroller programmer accepts COFF files as input, but most EPROM 
programmers do not. The object format converter converts a COFF object file into Tl- 
tagged, Intel, Motorola or Tektronix object format. The converted file can be downloaded 
to an EPROM programmer. 

• The main purpose of this development process is to produce a module that can be 
executed in a system that contains a MSP430 device. You can use one of several 
debugging tools to refine and correct your code before downloading it to a MSP430 
system. 
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1.2 Software Installation 

This section contains instructions for installing the assembly language tools. 

1.2.1 Installing the Tools on IBM PC/ATs or 100% Compatible Machines With PC- 

DOS, MS-DOS, OS/2 or MS-Windows 

The MSP430 assembly language software package is shipped on a double-sided, high- 
density disk. Your system must have at least 512K bytes of memory space and 1MB of 
harddisk space. 


First make a backup of the product disk. 

Insert the backup disk into the floppy disk drive of your choice. 
Change to that drive and enter: 

INSTALL 

Follow the instructions displayed on screen. 
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1.3 Getting Started 


The tools you will probably use most often are the assembler and the linker. This section 
provides a quick walkthrough so that you can get started without reading the whole user's 
guide. These examples show the most common methods for invoking the assembler and 
linker. 


1) Create two short source files to use for the walkthrough; call them fiiei.asm and 


file2.asm. 


filel.asm 


file2.asm 



.global addq 


.global 

addq 

start 

clr RIO 

addq 

inc 

RIO 


clr Rll 


inc 

Rll 



skp 

ret 


loop 

call #addq 


. end 



jnc loop 
. end 


2) Enter the following command to assemble filel .asm. 

asm430 filel 

3) The asm430 command invokes the MSP430 assembler; fiiei.asm is the input source 
file. 

If the input file extension is .asm, you don't have to specify the extension; the assembler 
uses .asm as the default. This example creates an object file called fiiei.obj. The 
assembler creates an object file only If there are no errors. You can specify a name for 
the object file, but if you don't, the assembler will append the .obj extension to the input 
filename. 

4) Now assemble f iie2 .asm; enter: 
asm430 file2 -1 

5) This time, the assembler creates an object file called fiie2 .obj. The -I (lowercase “L") 
option tells the assembler to create a listing file; the listing file for this example is called 

file2.1st. 

6) Link fiiei.obj and fiie2.obj; enter: 
lnk430 filel file2 -o prog.out 

7) The Ink430 command invokes the linker, fiiei.obj and fiie2.obj are the input object 
files. (If the input file extension is .obj, you don't have to specify the extension; the linker 
uses .obj as the default.) The linker combines fiiei.obj and fiie2.obj to create an 
executable object module called prog.out. The -o option supplies the name of the output 
module. 
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2 Introduction to Common Object File Format 

The assembler and linker create object files that can be executed by a MSP430 device. The 
format that these object files are in is called common object file format (COFF). 

COFF makes modular programming easier because it encourages you to think in terms of 
blocks of code and data when you write an assembly language program. These blocks are 
known as sections. Both the assembler and the linker provide directives that allow you to 
create and manipulate sections. 

For more information about COFF object file structure refer to the Appendix. 
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2.1 Sections 

The smallest unit of an object file is called a section. A section is a block of code or data that 
will ultimately occupy contiguous space in the MSP430 memory map. Each section of an 
object file is separate and distinct from the other sections. COFF object files always contain 
three default sections: 

.text section usually contains executable code. 

.data section usually contains initialized data. 

.bss section usually reserves space for uninitialized variables. 

In addition, the assembler and linker allow you to create, name, and link named sections that 
are used like the .data, .text, and .bss sections. 

It is important to note that there are two basic types of sections: 

Initialized sections contain data or code. The .text and .data sections are initialized; 

named sections created with the .sect assembler directive are also 
initialized. 

Uninitialized sections reserve space in the memory map for uninitialized data. The .bss 
section is uninitialized; named sections created with the .usect, 
reg, and .regpair assembler directive are also uninitialized. 

The assembler provides several directives that allow you to associate various portions of 
code and data with the appropriate sections. The assembler builds these sections during the 
assembly process, creating an object file that is organized like the object file shown in the 
following figure. 

One of the linker's functions is to relocate sections into the target memory map; this is called 
allocation. Because most systems contain several different types of memory, using sections 
can help you to use target memory more efficiently. All sections are independently 
relocatable; you can place different sections into various blocks of target memory. For 
example, you can define a section that contains an initialization routine and then allocate the 
routine into a portion of the memory map that contains ROM. 
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Object File Target File 


♦bss 

-^ 

RAM 

.data 

-► 

EEPROM 

Mm 


4 

4 

4 



-► 

f)OM 


Figure 2.1: Partitioning Memory Into Logical Blocks 
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2.2 How the Assembler Handles Sections 

The assembler's main function related to sections is to identify the portions of an assembly 
language program that belong in a particular section. The assembler has seven directives 
that support this function: 

• .bss 

• .data 

• .sect 

• .text 

• .usect 

The .bss and .usect directives create uninitialized sections] the .text, .data, and .sect 
directives create initialized sections. 


Note: Default Section Directive 

If you don't use any of the sections directives, the assembler assembles everything into 
the .text section. 


2.2.1 Uninitialized Sections 

Uninitialized sections reserve space in l\/ISP430 memory; they are usually allocated into 
RAM. These sections have no actual contents in the object file; they simply reserve memory. 
A program can use this space at runtime for creating and storing variables. 

Uninitialized data areas are built by using the .bss and .usect assembler directives. The .bss 
directive reserves space in the .bss section. The .usect directive reserves space in a specific 
uninitialized named section. If the section name is specified, the space is reserved in the 
named section. Each time you invoke one of these directives, the assembler reserves more 
space in the appropriate section. 

The syntaxes for these directives are: 

.bss name l,size in bytes] 

symbol .usect “section name", size in byte 

symbol points to the first byte reserved by this invocation of the .bss or .usect 
directive. The symbol corresponds to the name of the variable that you're 
reserving space for. It can be referenced by any other section and can also be 
declared as a global symbol (with the .global assembler directive). 

size is an absolute expression. The .bss directive reserves size bytes in the .bss 

section; the .usect directive reserves size bytes in section name. If the section 
name is specified, the space is reserved in the named section.The default size 
for .bss is one byte. 
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section name tells the assembler which named section to reserve space in. 

The .text, .data, and .sect directives tell the assembler to stop assembling into the current 
section and begin assembling into the indicated section. The .bss and .usect, however, do 
not end the current section and begin a new one; they simply “escape" from the current 
section temporarily. The .bss and .usect directives can appear anywhere in an initialized 
section without affecting the contents of the initialized section. 

2.2.2 Initialized Sections 

Initialized sections contain executable code or initialized data. The contents of these sections 
are stored in the object file and placed in MSP430 memory when the program is loaded. 
Each initialized section is separately relocatable and may reference symbols that are defined 
in other sections. The linker automatically resolves these section-relative references. 

Three directives tell the assembler to place code or data into a section. The syntaxes for 
these directives are: 

.text 

.data 

.sect “section name" 

When the assembler encounters one of these directives, it stops assembling into the current 
section (acting as an implied “end current section" command). It then assembles subsequent 
code into the respective section until it encounters another .text, .data, or .sect directive. 

Sections are built up through an iterative process. For example, when the assembler first 
encounters a .data directive, the .data section is empty. The statements following this first 
.data directive are assembled into the .data section (until the assembler encounters a .text or 
.sect directive). If the assembler encounters subsequent .data directives, it adds the state¬ 
ments following these .data directives to the statements that are already in the .data section. 
This creates a single .data section that can be allocated contiguously into memory. 

2.2.3 Named Sections 

Named sections are sections that you create. You can use them like the default .text, .data, 
and .bss sections, but they are assembled separately from the default sections. 

For example, repeated use of the .text directive builds up a single .text section in the object 
file. When linked, this .text section is allocated Into memory as a single unit. Suppose there is 
a portion of executable code (perhaps an initialization routine) that you don't want allocated 
with .text. If you assemble this segment of code into a named section, it will be assembled 
separately from .text, and you will be able to allocate it into memory separately from .text. 
Note that you can also assemble initialized data that is separate from the .data section, and 
you can reserve space for uninitialized variables that is separate from the .bss section. 
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Two directives let you create named sections: 

• The .usect directive creates sections that are used like the .bss section. These sections 
reserve space in RAM for variables. 

• The .sect directive creates sections that can contain code or data, similar to the default 
.text and .data sections. The .sect directive creates named sections with relocatable 
addresses. 

The syntaxes for these directives are: 
symbol .usect “section name", size 
.sect “section name" 

The section name parameter is the name of the section. Section names are significant to 8 
characters. You can create up to 32,767 separate named sections. 

Each time you invoke one of these directives with a new name, you create a new named 
section. Each time you invoke one of these directives with a name that was already used, the 
assembler assembles code or data (or reserves space) into the section with that name. You 
cannot use the same names with different directives. That is, you cannot create a section 
with the .usect directive and then try to use the same section with .sect. 

2.2.4 Section Program Counters 

The assembler maintains a separate program counter for each section. These program 
counters are known as section program counters, or SPCs. 

An SPC represents the current address within a section of code or data. Initially, the 
assembler sets each SPC to 0. As the assembler fills a section with code or data, it 
increments the appropriate SPC. If you resume assembling into a section, the assembler 
remembers the appropriate SPCs previous value and continues incrementing the SPC at 
that point. 

The assembler treats each section as if It begins at address 0; the linker relocates each 
section according to its final location in the memory map. 

2.2.5 An Example That Uses Sections Directives 

The figure on the next page shows how you can build COFF sections incrementally, using 
the sections directives to swap back and forth between the different sections. You can use 
sections directives to: 

• Begin assembling into a section for the first time. 

• Continue assembling into a section that already contains code. In this case, the 
assembler simply appends the new code to the code that is already in the section. 
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The SPCs are modified during assembly. A line in a listing file has four fields: 
Field 1 contains the source code line counter. 

Field 2 contains the section program counter. 

Field 3 contains the object code. 


Field 4 contains the original source statement. 


1 



********************************************** 

2 



** Assemble an initialized table into .data ** 

3 



*********************************************** 

4 

0000 


. data 

5 

0000 

0011 

coeff .word Ollh, 022h 


0002 

0022 


7 



i<i':i<i<-k-k'k-k-k'k-k-k-k'k'k’k'k-k'k-k'k-k'k'ki<'k-k’ki<^'ki<:'k-ki<'k-k'k'k'k'k'k-k‘k'k-^ 

8 



** Reserve space in .bss for a variable ** 

9 



********************************************** 

10 




11 

0000 


.bss buffer, 10 

12 



********************************************** 

13 



** Still in .data ** 

14 



********************************************** 

15 




16 

0004 

0123 

ptr .word 0123h 

17 



********************************************** 

18 



** Assemble code into the .text section ** 

19 



********************************************** 

20 




21 

0000 


. text 

22 

0000 

5504 

addl add R5,R4 

23 

0002 

4304 

clr R4 

24 

0004 

’ 23fd 

j nz addl 

25 



-k-k-k‘k'k-k-k-k-k'k'k-k-k‘k'k'k‘k-k'k'k-k:k-k-k-k'k‘k-k'k'k'k-k-k-k'k'k-kic'k-k'kic-k'k'k'k 

26 



** Assemble more data into the .data section** 

27 



********************************************** 

28 




29 

0006 


. data 

30 

0006 

OOaa 

ivals .word Oaah, Obbh 


0008 

OObb 


31 



********************************************** 

32 



** define another section for more variables** 

33 



********************************************** 

34 




35 

0000 


var2 .usect "newvars",! 

36 

0001 


inbuf .usect "newvars",7 

37 



********************************************** 

38 



** Assembler more code into .text ** 

39 



********************************************** 

40 




41 

0006 


. text 

42 

0006 

4524 

acode mov @R5, R4 

43 

0008 

4407 

mov R4, R7 

44 



********************************************** 

45 



** Define a named section for int. vectors ** 

46 



********************************************** 

47 




48 

0000 


.sect "vectors" 

49 

0000 

■ 0000 

.word addl, acode 


0002 

\ ^ / 

' 0006 

^ 

\ „ / 

▼ 



T 

Field 1 

Field 2 

Field 3 

Field 4 


Figure 2.2: Using Sections Directives 
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The listing file creates five sections: 

.text contains 10 bytes of object code. 

.data contains 10 bytes of object code. 

vectors is a named section created with the .sect directive; it contains 4 bytes of 
initialized data. 

.bss reserves 10 bytes in memory. 

newvars is a named section created with the .usect directive; it reserves 8 bytes in 
memory. 


The second column shows the object code that is assembled into these sections; the first 
column shows the source statements that generated the object code. 


Line Numbers 

22 

23 

24 

42 

43 

5 

5 

16 

30 

30 

49 

49 

11 


35 

36 


Object Code 

5504 

4304 

23FD 

4524 

4407 


0011 

0022 

0123 

OOAA 

OOBB 


0000 

0006 


No data 
10 bytes 
reserved 

No data 
8 bytes 
reserved 


Section 

.text 


.data 


vectors 

■bss 


newvars 


Figure 2.3: Generated Object Code according to previous source code example 
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2.3 How the Linker Handles Sections 

The linker has two main functions related to sections. First, the linker uses the sections in 
COFF object files as building blocks; it combines input sections (when more than one file is 
being linked) to create output sections in an executable COFF output module. Second, the 
linker chooses memory addresses for the output sections. 

The linker provides two directives that support these functions: 

• The MEMORY directive allows you to define the memory map of a target system. You 
can name portions of memory and specify their starting addresses and their lengths. 

• The SECTIONS directive tells the linker how to combine input sections and where to 
place the output sections in memory. 

it is not always necessary to use linker directives. If you don't use them, the linker uses the 
target processor's default allocation algorithm. When you do use linker directives, you must 
specify them in a linker command file. 
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2.3.1 Default Memory Allocation 


file1 .obj 


.bss 


.text 


•data 


IrBt 

aectwtfi; 




file2.obj 


.bss 


•text 




;named Button] 


j 




Executable 

Object Module 

Memory Map 

■'■'■"■"filei;:'"/’ ■■ 

(bss) 

tile 2 
(.bss) 


Space for 
Variables 

(.bss) 

file 1 
(.text) 

file 2 
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Executable 

Code 
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Initialized 

Data 

(.data) 

Bi 


Ihit 



Tables 


Figure 2.4: Combining Input Sections to Form an Executable Object Module 

In the figure, filet .obj and file2.obj have been assembled to be used as linker input. Each 
contains the .text, .data, and .bss default sections; in addition, each contains a named 
section. The executable output module shows the combined sections. The linker combines 
filet .text with file2.text to form one .text section, then combines the .data sections, then the 
.bss sections, and finally places the named sections at the end. The memory map shows 
how the sections are put into memory. 
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2.3.2 Placing Sections in the Memory Map 

The figure also illustrates the linker's default methods for combining sections. Sometimes 
you may not want to use the default setup. For example, you may not want all of the .text 
sections to be combined into a single .text section. Or you might want a named section 
placed where the .data section would normally be allocated. Most memory maps comprise 
various types of memories (RAM, ROM, EPROM, etc.) in varying amounts; you may want to 
place a section in a particular type of memory. 

• The MEMORY directive allows you to define the memory map for your particular system. 

• The SECTIONS directive lets you build sections and place them into memory. 
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2.4 Relocation 

The assembler treats each section as if it began at address 0. All relocatable symbols 
(labels) are relative to address 0 in their sections. Of course, all sections can't actually begin 
at address 0 in memory, so the linker relocates sections by: 

• allocating sections into the memory map so that they begin at the appropriate address. 

• adjusting symbol values to correspond to the new section addresses. 

• adjusting references to relocated symbols to reflect the adjusted symbol values. 

The linker uses relocation entries to adjust references to symbol values. The assembler 
creates a relocation entry each time a relocatable symbol is referenced. The linker then uses 
these entries to patch the references after the symbols are relocated. 


1 




.global X 




2 

0000 



. text 




3 

0000 

140300000 


br #x 

;uses an 

external 

relocation 

4 

0004 

' 12B00008 


call tty 

;uses an 

internal 

relocation 

5 

0008 

5504 

y: 

add R5, R4 

;defines 

internal 

relocation 


Figure 2.5: An Example of Code That Generates Relocation Entries 

Both symbols x and y are relocatable, y Is defined in the .text section of this module; x is 
defined in some other module. When the code is assembled, x has a value of 0 (the 
assembler assumes all undefined external symbols have values of 0), and y has a value of 8 
(relative to address 0 in the .text section). The assembler generates two relocation entries, 
one for x and one for y. The reference to x is an external reference (indicated by the ! 
character in the listing). The reference to y Is to an internally defined relocatable symbol 
(indicated by the ' character in the listing). 

After the code is linked, suppose that x is relocated to address 7100h. Suppose also that the 
.text section is relocated to begin at address 7200h; y now has a relocated value of 7208h. 
The linker uses the two relocation entries to patch the two references in the object code: 

40300000 br #x becomes 40307100 

12B00008 call #y beCOmeS 12B07208 

Each section in a COFF object file has a table of relocation entries. The table contains one 
relocation entry for each relocatable reference in the section. The linker usually removes 
relocation entries after it uses them. This prevents the output file from being relocated again 
(if it is relinked or when it is loaded). A file that contains no relocation entries is an absolute 
file (all its addresses are absolute addresses). If you want the linker to retain relocation 
entries, invoke the linker with the -r option. 
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2.5 Runtime Relocation 

It may be necessary or desirable at times to load code into one area of memory and run it in 
another. For example, you may have performance-critical code in a ROM-based system. 
The code must be loaded into ROM but would run much faster if it were in RAM. 

The linker provides a simple way to specify this. In the SECTIONS directive, you can 
optionally direct the linker to allocate a section twice: once to set its load address, and again 
to set its run address. 

Use the load keyword for the load address and the run keyword for the run address. 

The load address determines where a loader will place the raw data for the section. Any 
references to the section (such as labels in it) refer to its run address. The application must 
copy the section from its load address to its run address; this does not happen automatically 
just because you specify a separate run address. 

If you provide only one allocation (either load or run) for a section, the section is allocated 
only once and will load and run at the same address. If you provide both allocations, the 
section is actually allocated as if it were two different sections of the same size. 

Uninitialized sections (such as .bss) are not loaded, so the only significant address is the run 
address. The linker allocates uninitialized sections only once: if you specify both run and 
load addresses, the linker warns you and ignores the load address. 
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2.6 Loading a Program 

The linker produces executable COFF object modules. An executable object file has the 
same COFF format as object files that are used as linker input; however, the sections in an 
executable object file are combined and relocated to fit into target memory. 

In order to run a program, the data in the executable object module must be transferred, or 
loaded, into target system memory. 

Several methods can be used for loading a program, depending on the execution 
environment. Some of the more common situations are listed below. 

• The MSP430 development tools (In-Circuit-Emulator and Evaluation Module) provide 
COFF object module loading capabilities. 

• You can use the object format converter (the rom430, which is shipped as part of the 
assembly language package) to convert the executable COFF object module into one of 
several object file formats. You can then use the converted file with almost any EPROM 
programmer to burn the program into an EPROM. 
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2.7 Symbols in a COFF File 

A COFF file contains a symbol table that stores information about symbols in the program. 
The linker uses this table when it performs relocation. Debugging tools can also use the 
symbol table to provide symbolic debugging. 


2.7.1 External Symbols 


External symbols are symbols that are defined in one module and referenced in another 
module. You can use the .def, .ref, or .global directives to identify symbols as external: 
Defined (.def) Defined in the current module and used in another module 

Referenced (.ref) Referenced in the current module, but defined in another module 

Global (.global) May be either of the above 

The following code segment illustrates these definitions. 


x: ADD #56h, R4 

BR #y 

.global X 

.global y 


Define x 
Reference y 
DEF of X 
REF of y 


The .global definition of x says that it is an external symbol defined in this module and that 
other modules can reference x. The .global definition of y says that it is an undefined symbol 
that is defined in some other module. 


The assembler places both x and y in the object file's symbol table. When the file is linked 
with other object files, the entry for x defines unresolved references to x from other files. The 
entry for y causes the linker to look through the symbol tables of other files for y's definition. 

The linker must match all references with corresponding definitions. If the linker cannot find a 
symbol's definition, it prints an error message about the unresolved reference. This type of 
error prevents the linker from creating an executable object module. 


2.7.2 The Symbol Table 

The assembler always generates an entry in the symbol table when it encounters an external 
symbol (both definitions and references). The assembler also creates special symbols that 
point to the beginning of each section; the linker uses these symbols to relocate references 
to other symbols in a section. 

The assembler does not usually create symbol table entries for any other type of symbol, 
because the linker does not use them. For example, labels are not included in the symbol 
table unless they are declared with .global. For symbolic debugging purposes, it is 
sometimes useful to have entries in the symbol table for each symbol in a program. To 
accomplish this, invoke the assembler with the -s option. 
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3 Assembler Description 

The assembler translates assembly language source files into machine language object files. 
These files are in common object file format (COFF). Source files can contain the following 
assembly language elements: 

Assembler directives 

Assembly language instructions 

Macro directives 

This two-pass assembler does the following: 

• Processes the source statements in a text file to produce a relocatable object file. 

• Produces a source listing (if requested) and provides you with control over this listing. 

• Allows you to segment your code Into sections and maintain an SPC (section program 
counter) for each section of object code. 

• Defines and references global symbols and appends a cross-reference listing to the 
source listing (if requested). 

• Assembles conditional blocks. 

• Supports macros, allowing you to define macros inline or in a library. 
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3.1 Assembler Development Flow 

The figure illustrates the assembler's role In the assembly language development flow. The 
assembler accepts assembly language source files as input. 



Figure 3.1: Assembler Development Flow 
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3.2 Invoking the Assembler 

To invoke the assembler, enter the following: 

asm430 [input file [object file [listing file [ rawdata file]]]] [-options] 


asm430 is the command that invokes the assembler. 

input file names the assembly language source file. If you do not supply an extension, the 
assembler assumes that the Input file has the default extension .asm. If you do 
not supply an input filename when you invoke the assembler, the assembler will 
prompt you for one. 

object file names the object file that the assembler creates. If you do not supply an 
extension, the assembler uses .objas a default extension. If you do not supply an 
object file, the assembler creates a file that uses the input file name with the .obj 
extension. 


listing file names the optional listing file that the assembler can create. If you do not supply 
a name for a listing file, the assembler does not create one unless you use the -I 
option. In this case, the assembler uses the input filename. If you do not supply 
an extension, the assembler uses .1stas a default extension. 


rawdata file names the optional ascii-format object file that the assembler can create. If you 
do not supply a name for the rawdata file, the assembler does not create one 
unless you use the -z option. In this case, the assembler uses the input filename. 
If you do not supply an extension, the assembler uses .txt as a default extension 

options identifies the assembler options that you want to use. 


Options are not case-sensitive and can appear anywhere on the command line 
following the command. Precede each option with a hyphen (-). You can string 
the options together; for example, -Ic is equivalent to -I -c. The valid assembler 
options are as follows: 


-a creates an absolute listing. When you use -a, the assembler does not 
produce an object file. The absolute listing option is used in conjunction 
with the absolute lister. 


-b suppress banner on all pages except page 1. 

-c makes case insignificant. For example, the symbols ABC and abc will be 
equivalent. If you do not use this option, case is significant. 

-i specifies a directory where the assembler can find files named by the 
.copy, .include, or .mlib directives. The format of the -i option is -\path- 
name. You can specify up to 10 directories in this manner; each path¬ 
name must be preceded by the -i option. 

-I (lowercase “L") produces a listing file. 

-q (quiet) suppresses the banner and all progress information. 
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-s puts all defined symbols in the object file's symbol table. Usually, the 
assembler puts only global symbols into the symbol table. When you use 
-s, symbols that are defined as labels or as assembly-time constants are 
also placed in the symbol table. 

-X produces a cross-reference table and appends it to the end of the listing 
file. If you do not request a listing file, the assembler creates one anyway. 

-z creates an objext file in ascii format containing no relocation and debug 
information. The generation of the COFF object file is not affected. This 
option is used in conjunction with the evaluation module. 
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3.3 Naming Alternate Directories for Assembler Input 

The .copy, .include, and .mlib directives tell the assembler to use code from external files. 
The .copy and .include directives tell the assembler to read source statements from another 
file, and the .mlib directive names a library Jhat contains macro functions. The syntaxes for 
these directives are: 

.copy "filename" 

.include "filename" 

.mlib "filename" 

The filename names a copy/include file that the assembler reads statements from or a macro 
library that contains macro definitions. The filename may be a complete pathname, a partial 
pathname, or a filename with no path information. The assembler searches for the file in; 

1) The directory that contains the current source file. The current source file is the file being 
assembled when the .copy, .include, or .mlib directive is encountered. 

2) Any directories named with the -i assembler option. 

3) Any directories set with the environment variable A_DIR. 

You can augment the assembler's directory search algorithm by using the -i assembler 
option or the A_DIR environment variable. 

3.3.1 -i Assembler Option 

The -i assembler option names an alternate directory that contains copy/include files or 
macro libraries. The format of the -i option is as follows: 

asm430 -Ipathname source filename 

You can use up to 10 -i options per invocation; each -i option names one pathname. In 
assembly source, you can use the .copy, .include, or .mlib directive without specifying any 
path information. If the assembler doesn't find the file in the directory that contains the 
current source file, it searches the paths provided by the -i options. 

For example, assume that a file called source.asm is in the current directory; source.asm 
contains the following directive statement: 

.copy "copy.asm" 
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Pathname for copy.asm 

Invocation Command 

c:\430\filesXcopy.asm 

asm430 -ic:\430\files source.asm 






The assembler first searches for copy.asm in the current directory because source.asm is in 
the current directory. Then, the assembler searches in the directory named with the -i option. 

3.3.2 Environment Variable (A_DIR) 

An environment variable is a system symbol that you define and assign a string to. The 
assembler uses the environment variable A_DIR to name alternate directories that contain 
copy/include files or macro libraries. The command for assigning the environment variable is 
as follows; 

DOS set A_DiR =: pathname;anotherpathname ... 

The pathnames are directories that contain copy/include files or macro libraries. You can 
separate the pathnames with a semicolon or with blanks. In assembly source, you can use 
the .copy, .include, or .mlib directive without specifying any path information. If the assembler 
doesn't find the file in the directory that contains the current source file or in directories 
named by -i, it searches the paths named by the environment variable. 

For example, assume that a file called source.asm contains these statements: 

.copy "copyl.asm" 

.copy "copy2.asm" 


Pathname 

Invocation Command 

c : \ 430\filesXcopyl.asm 
c:\dsys\copy2.asm 

set A_DIR=c:\dsys; c:\exec\source 
asm430 -ic:\430\files source.asm 






The assembler first searches for copyl.asm and copy2.asm in the current directory because 
source.asm is in the current directory. Then the assembler searches in the directory named 
with the -i option and finds copyl.asm. Finally, the assembler searches the directory named 
with A_DIR and finds copy2.asm. 

Note that the environment variable remains set until you reboot the system or reset the 
variable by entering one of these commands: 

DOS set A_DIR= 
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3.4 Source Statement Format 

MSP430 assembly language source programs consist of source statements that can contain 
assembler directives, assembly language instructions, macro directives, and comments. 
Source statement lines can be as long as the source file format allows, but the assembler 
reads up to 200 characters per line. If a statement contains more than 200 characters, the 
assembler truncates the line and issues a warning. 

The next several lines show examples of source statements: 

sym . equ 2 ; Symbol sym = 2 

Begin: ADD #sym+5,Rll ; Add (sym+5) to contents of Rll 

.word 016h ; Initialize a word with 016h 

A source statement can contain four ordered fields. The general syntax for source 
statements is as follows: 

[label] [:] mnemonic [operand list] [;comment] 

Follow these guidelines: 

• All statements must begin with a label, a blank, an asterisk, or a semicolon. 

• Labels are optional; if used, they must begin in column 1. 

• One or more blanks must separate each field. Note that tab characters are equivalent to 
blanks. 

• Comments are optional. Comments that begin in column 1 can begin with an asterisk or 
a semicolon (* or ;), but comments that begin in any other column must begin with a 
semicolon. 


Label Field - 

Labels are optional for all assembly language instructions and for most (but not all) 
assembler directives. When used, a label must begin in column 1 of a source statement. A 
label can contain up to 32 alphanumeric characters (A-Z, a-z, 0-9, _, and $). Labels are 
case-sensitive, and the first character cannot be a number. A label can be followed by a 
colon (:); the colon is not treated as part of the label name. If you don't use a label, the first 
character position must contain a blank, a semicolon, or an asterisk. 

When you use a label, its value is the current value of the section program counter (the label 
points to the statement it's associated with). If, for example, you use the .word directive to 
initialize several words, a label would point to the first word. In the following example, the 
label Start has the value 40h. 


9 

003F 


* Assume some other code was assembled 

10 

0040 

OOOA 

Start: .word 0Ah,3,7 


0041 

0003 



0043 

0007 
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A label on a line by itself is a valid statement. It assigns the current value of the section 
program counter to the label; this is equivalent to the following directive statement: 

label . equ $ ; $ provides the current value of the SPC 

When a label appears on a line by itself, it points to the instruction on the next line (the SPC 
is not incremented): 

3 0050 Here: 

4 0050 0003 .word 3 

Mnemonic Field - 

The mnemonic field follows the label field. The mnemonic field cannot start in column 1, or it 
would be interpreted as a label. The mnemonic field can contain one of the following 
opcodes: 

• Machine-instruction mnemonic (such as ADC, MOV, POP) 

• Assembler directive (such as .data, .list, .equ) 

• Macro directive (such as .macro, .var, .mexit) 

• A macro call 


Operand Field - 

The operand field is a list of operands that follow the mnemonic field. An operand can be a 
constant, a symbol, or a combination of constants and symbols in an expression. You must 
separate operands with commas. 

• Operand Prefixes for Instructions 

The assembler allows you to specify that a constant, symbol, or expression should be 
used as an address, an immediate value, or an indirect value. The following rules apply 
to the operands of instructions. 

• No prefix — the operand is an address or a register. If you do not use a prefix with 
an operand, the assembler treats an operand representing a constant value as an 
absolute address. When the operand is a label, the assembler generates a symbolic 
address. A register name specifies the contents of the named register. This are 
examples of instructions that use operands without prefixes: 

Label: ADD 0FFFEh,R5 ; add contents of absolute address to register 

ADD Label,R5 ; add contents of symbolic address to register 

• & prefix — the operand is an absolute address. If you use the & sign as a prefix, 
the assembler treats the operand as an absolute address, similar to using no prefix. 
The operand has to specify a constant value: 

MOV &200h,R5 
MOV 200h,R5 

Both instructions generate the same object code, moving the contents of absolute 
address 200h to register R5. 
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. # prefix — the operand is an immediate value. If you use the # sign as a prefix, the 

assembler treats the operand as an immediate value. This is true even when the 
operand is an address; the assembler treats the address as a value instead of using 
the contents of the address. This is an example of an instruction that uses an 
operand with the # prefix: 

Label: ADD #123,R5 

The operand #123 is an immediate value. The assembler adds 123 (decimal) to the 
contents of register R5. 

• @ prefix — the operand is an indirect address. If you use the @ sign as a prefix, 

the assembler treats the operand as an indirect address; that is, it uses the contents 
of the operand as an address. This is an example of an instruction that uses an 
operand with the @ prefix: 

Label: MOV @R4,R4 

The operand @R4 specifies an indirect address. The assembler goes to the address 
specified by the contents of register R4 and then moves the contents of that location 
to register R4. 

• Immediate Addressing for Directives 

The immediate addressing mode is used mostly with instructions; in some cases, it can 
also be used with the operands of directives. 

Usually, it is not necessary to use the immediate addressing mode for directives. 
Compare the following statements: 

ADD #10, R4 
.byte 10 

In the first statement, the immediate addressing mode is necessary to tell the assembler 
to add the value 10 to register R4. In the second statement, however, immediate 
addressing is not used; the assembler expects the operand to be a value and initializes a 
byte with the value 10. 


Comment Field- 

A comment can begin in any column and extends to the end of the source line. A comment 
can contain any ASCII character, including blanks. Comments are printed in the assembly 
source listing, but they do not affect the assembly. 

A source statement that contains only a comment is valid. If It begins in column 1, it can start 
with a semicolon ( ; ) or an asterisk ( *). Comments that begin anywhere else on the line 
must begin with a semicolon. The asterisk identifies a comment only if it appears in column 
1 . 
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3.5 Constants 

The assembler supports six types of constants: 

• Binary integer constants 

• Octal integer constants 

• Decimal integer constants 

• Hexadecimal integer constants 

• Character constants 

• Assembly-time constants 

The assembler maintains each constant internally as a 32-bit quantity. Note that constants 
are not sign extended. For example, the constant OFFH is equal to OOFF (base 16) or 255 
(base 10); it does not equal -1. 

Binary Integers- 

A binary integer constant is a string of up to 16 binary digits (Os and Is) followed by the suffix 
B (or b). If fewer than 16 digits are specified, the assembler right-justifies the value and 
zero-fills the unspecified bits. These are examples of valid binary constants: 

OOOOOOOOBConstant equal to Oiq or O -(0 
0100000b Constant equal to 32i q or 20«j q 
01b Constant equal to 1 <10 or 1 10 

11111 OOOBConstant equal to 248i q or OFS-j 0 

Octal Integers - 

An octal integer constant is a string of up to 6 octal digits (0 through 7) followed by the suffix 
Q (or q). These are examples of valid octal constants: 

1 0Q Constant equal to 8 -| 0 or 8 -| 0 
1 0OOOOQ Constant equal to 32,768i q or 8000<| 0 
226Q Constant equal to 1 SO-j q or 96i 0 

Decimal Integers- 

A decimal integer constant is a string of decimal digits, ranging from? -32,768 to 65,535. 
These are examples of valid decimal constants: 

1000 Constant equal to 1 0 OO 1 q or 3E8-| 0 

-32768 Constant equal to -32,768<| q or 8000<| 0 

25 Constant equal to 25-| q or 19-| 0 
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Hexadecimal Integers- 

A hexadecimal integer constant is a string of up to 4 hexadecimal digits followed by the suffix 
H (or h). Hexadecimal digits include the decimal values 0-9 and the letters A-F or a-f. A 
hexadecimal constant must begin with a decimal value (0-9). If fewer than 4 hexadecimal 
digits are specified, the assembler right-justifies the bits. These are examples of valid 
hexadecimal constants: 

78h Constant equal to 1 201 0 o*' 0078i 0 

OFh Constant equal to 1 S-j q or OOOF 15 
37ACh Constant equal to 14,252i q or 37ACi e 

Character Constants -- 

A character constant is a single character enclosed in single quotes. The characters are 
represented internally as 8-bit ASCII characters. Two consecutive single quotes are required 
to represent each single quote that is part of a character constant. A character constant 
consisting only of two single quotes is valid and is assigned the value 0. These are examples 
of valid character constants: 

a' Defines the character constant a and Is represented Internally as 61 15 

'C Defines the character constant C and Is represented Internally as 43-|0 

" " Defines the character constant "" and Is represented Internally as 27i0 

Defines a null character and is represented Internally as OO 10 

Note the difference between character constants and character strings. A character constant 
represents a single integer value; a string is a list of characters. 

Assembly-Time Constants- 

If you use the .equ directive to assign a value to a symbol, the symbol becomes a constant. 
In order to use this constant in expressions, the value that is assigned to it must be absolute. 
For example: 

sym . equ 3 

MOV #sym,RIO 

You can also use the .equ directive to assign symbolic constants for register names. In this 
case, the symbol becomes a synonym for the register: 

sym .equ R14 

MOV #10,sym 
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3.6 Character Strings 

A character string is a string of characters enclosed in double quotes. Double quotes that are 
part of character strings are represented by two consecutive double quotes. The maximum 
length of a string varies and is defined for each directive that requires a character string. 
Characters are represented internally as 8-bit ASCII characters. Appendix lists valid 
characters. 

These are examples of valid character strings: 

"sample program" defines a 14-character string, sampie program 

"PLAN ""C defines an 8-character string, PLAN "C" 

Character strings are used for the following: 

• Filenames, as in .copy "filename" 

• Section names, as in .sect "section name" 

• Data initialization directives, as in .byte "charstring" 

• Operand of .string or .byte directive 
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3.7 Symbols 

Symbols are used as labels, constants, and substitution symbols. A symbol name is a string 
of up to 32 alphanumeric characters (A-Z, a-z, 0-9, $, _and?). The first character in a symbol 
cannot be a number; symbols cannot contain embedded blanks. The symbols you define are 
case sensitive; for example, the assembler recognizes ABC, Abe, and abc as three unique 
symbols. You can override case sensitivity with the -c assembler option. This type of symbol 
is valid only during the assembly in which it is defined, unless you use the .global directive to 
declare it as an external symbol. 

Labels- 

Symbols that are used as labels become symbolic addresses that are associated with 
locations in the program. A label used locally within a file must be unique. Mnemonic op¬ 
codes and assembler directive names (without the prefix) are valid label names. 

Labels can also be used as the operand of a .global, .ref, .def, or .bss directive; for example: 

.global labell 

label2 nop 

mov labell, R4 

br label2 


Local Labels- 

Local labels are a special type of label whose scope and effect are only temporary. A local 
label has the form $n, where n is a decimal digit in the range 0-9. For example, $4 and $1 
are valid local labels. 

Normal labels must be unique (thoy can be declared only once), and they can be used as 
constants in the operand field. Lee ;; labels, however, can be undefined and defined again. If 
a local label is used as an operand, it can be used only as an operand for a 10-bit jump 
instruction. 

A local label can be undefined, or reset, in one of four ways: 

• By the .newblock directive 

• By changing sections (using a .sect, .text, or .data directive) 

• By entering an include file (specified by the .include or .copy directive) 

• By leaving an include file (specified by the .include or .copy directive) 
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This is an example of code that declares and uses a local label legally; 

Labell: movRl2,Rl3 

jnz $1 
mov #-l, R13 

$1 cmpRl3,R4 

.newblock; Undefine $1 so it can be used again 
jne $1 
inc R13 

$1 addR13,R14 

The following code uses a local label Illegally: 

Labell: movRl2,Rl3 

jnz $1 
mov #-l,R13 
$1 cmp R3,R4 

jne $1 
inc R13 

$1 addRl3,R14 ; WRONG — $1 is multiply defined 

Local labels are especially useful in macros. If a macro contains a normal label and is called 
more than once, the assembler issues a multiple-definition error. However, if you use a 
local label within a macro and then use .newblock within the macro, the local label is used 
and reset each time the macro is expanded. 

Up to ten local labels can be in effect at one time. After you undefine a local label, you can 
define it and use it again. Local labels do not appear in the object code symbol table. 

Constants- 

Symbols can be set to constant values. By using constants, you can equate meaningful 
names with constant values. The .equ, .set, and .struct/.tag/.endstruct directives enable you 
to set constants to symbolic names. Symbolic constants cannot be redefined. The following 
example shows how these directives can be used: 

K .set 1024 ; constant definitions 

maxbuf .set 2*K 

item .struct 

.byte value 
.byte delta 
i_len .endstruct 


array 

. tag 

item 

; array declaration 


.bss 

array, i_len*K 



MOV 

array.delta,R4 

; array+1 


The assembler also has several predefined symbolic constants; these are discussed in the 
next subsection. 


; item structure definition 
; constant offsets value = 0 
; constant offsets delta = 1 
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Symbolic Constants - 

The assembler has several predefined symbols, including the following: 

• $, the dollar sign character, represents the current value of the section program counter 
(SPC). 

• Register symbols, which are of the form Rn or rn , where n is an expression that 
evaluates in the range 0-15. (If the number is greater than 15, the symbol is not 
considered a register symbol.) The number may be decimal. Note that PC, SP and SR 
are valid register symbols; they represent registers with special functions (RO - R3). 


Substitutions Symbols - 

Symbols can be assigned a string value (variable). This enables you to alias character 
strings by equating them to symbolic names. Symbols that represent character strings are 
called substitution symbols. When the assembler encounters a substitution symbol, its string 
value is substituted for the symbol name. Unlike symbolic constants, substitution symbols 
can be redefined. 

A string can be assigned to a substitution symbol anywhere within a program; for example: 


. asg 

"R13", 

SPl 

. asg 


pis 

. asg 

"-5" , 

minS 

ADD 

# min5. 

SPl 


When you are using macros, substitution symbols are important because macro parameters 
are actually substitutions symbols that are assigned a macro argument. The following code 
shows how substitution symbols are used in macros: 

add2 .macro src,dest ; add2 macro definition 

mov src,R4 

mov R4,R5 

mov dest,R4 

add R5,R4 

mov R4,dest 

. endm 

*add2 invocation 

add2 loci, loc2 
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3.8 Expressions 

An expression is a constant, a symbol, or a series of constants and symbols separated by 
arithmetic operators. The range of valid expression values is -32,768 to 65,535. These are 
the three main factors that influence the order of expression evaluation: 

Parentheses Expressions that are enclosed in parentheses are always 

evaluated first. 

8/(4/2) = 4, but 8/4/2 = 1 

Note that you cannot substitute braces ({}) or brackets ( [ ] ) 
for parentheses. 

Precedence groups Operators, listed in the next table, are divided into nine 

precedence groups. When the order of expression evaluation is 
not determined by parentheses, the highest precedence 
operation is evaluated first. 

8-1-4/2 = 10 (4/2 is evaluated first) 

Left-to-right evaluation When parentheses and precedence groups do not determine 
the order of expression evaluation, the expressions are 
evaluated from left to right. Note that the highest precedence 
group is evaluated from right to left. 

8/4*2 = 4, but 8/(4*2) = 1 
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3.8.1 Operators 


Group 

Operator 

Description 

1 

+ 

Unary plus 


- 

Unary minus 


! 

1s complement 

Logical NOT 

2 

* 

Multiplication 


/ 

Division 


% 

Modulo 

3 

+ 

Addition 


- 

Subtraction 

4 

« 

Shift left 


» 

Shift right 

5 

< 

Less than 


<= 

Less than or equal to 


> 

Greater than 


>= 

Greater than or equal to 

6 

= (==) 

Equal to 


!= (<>) 

Not equal to 

7 

& 

Bitwise AND 

8 

A 

Bitwise XOR 

9 

I 

Bitwise OR 


Notes: 1) Operators in parentheses () indicate an alternate form. 

2) Group 1 operators are evaluated right to left. All other operators 
are evaluated left to right. 


Table 3.1 : Operators Used in Expressions (Precedence) 


3.8.2 Expression Overflow and Underflow 

The assembler checks for overflow and underflow conditions when arithmetic operations are 
performed at assembly time. The assembler issues a Value Truncated warning whenever an 
overflow or underflow occurs. The assembler does not check for overflow or underflow in 
multiplication. 
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3.8.3 Well-Defined Expressions 

Some assembler directives require well-defined expressions as operands. Well-defined 
expressions contain only symbols or assembly-time constants that are defined before they 
are encountered in the expression. The evaluation of a well-defined expression must be 
absolute. 

This is an example of a well-defined expression: 

lOOOh+X 

where X was previously defined as an absolute symbol. 

3.8.4 Conditional Expressions 

The assembler supports relational operators that can be used in any expression; they are 
especially useful for conditional assembly. Relational operators include the following: 


= Equal to 

= = 

Equal to 

! = Not equal to 

<> 

Not Equal to 

< Less than 

< = 

Less than or equal to 

> Greater than 

> = 

Greater than or equal to 


Conditional expressions evaluate to 1 if true and 0 if false, and may be used only on 
operands of equivalent types, e.g., absolute value compared to absolute value, but not 
absolute value compared to relocatable value. 

3.8.5 Relocatable Symbols and Legal Expressions 

The following table summarizes valid operations on absolute, relocatable, and external 
symbols. An expression cannot multiply or divide by a relocatable or external symbol. An 
expression cannot contain unresolved symbols that are relocatable with respect to different 
sections. 

Symbols that have been defined as global with the .global directive can also be used in 
expressions; in the table, these symbols are referred to as external. 
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If A is... 

If B is... 

A + B is... 

A-Bis... 

absolute 

absolute 

absolute 

absolute 

absolute 

relocatable 

relocatable 

illegal 

absolute 

external 

external 

illegal 

relocatable 

absolute 

relocatable 

relocatable 

relocatable 

relocatable 

illegal 

absolute * 

relocatable 

external 

illegal 

illegal 

external 

absolute 

external 

external 

external 

relocatable 

illegal 

illegal 

external 

external 

illegal 

illegal 


* A and B must be in the same section; otherwise, this is illegal. 

Table 3.2: Expressions With Absolute and Relocatable Symbols 


Here are some examples of expressions that use relocatable and absolute symbols. These 
examples use four symbols that are defined in the same section: 

.global extern_l /Defined in an external module 
intern_l: .word 'D' /Relocatable, defined in current module 

LABI: .equ 2 /LABI = 2 

intern_2: /Relocatable, defined in current module 

• Example 1; 

The first statement in this example puts the value 51 into register R4. The second 
statement puts the value 27 into register R4. 

MOV #(LAB1 + (4+3) * 7), R4 / R4 = 51 

MOV #(LAB1 + 4 + 3 * 7), R4 / R4 = 27 

• Example 2 

All legal expressions can be reduced to one of two forms; 

relocatable symbol ± absolute symbol 

or 

absolute value 


Unary operators can be applied only to absolute values; they cannot be applied to 
relocatable symbols. Expressions that cannot be reduced to contain only one relocatable 
symbol are illegal. The first statement in the following example is legal; the others are 
illegal. 


MOV 

extern_l - 

10, R4 

MOV 

10-extern_l 

, R4 

MOV 

-(internal) 

, R4 

MOV 

extern_l/10 

, R4 

MOV 

intern_l + 

extern_l,R4 


Legal 

Can't negate relocatable symbol 
Can't negate relocatable symbol 
/ is not an additive operator 
Multiple relocatables 
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• Example 3 

The first statement below is legal; although intern_1 and intern_2 are relocatable, their 
difference is absolute because they're in the same section. Subtracting one relocatable 
symbol from another reduces the expression to relocatable symbol + absolute value. The 
second statement is illegal because the sum of two relocatable symbols is not an 
absolute value. 

MOV intern_l - intern_2 + extern_l, R4 ; (legal) 

MOV intern_l + intern_2 + extern_l, R4 ; (illegal) 

• Example 4 

An external symbol's placement in an expression is important to expression evaluation. 
Although the statement below is similar to the first statement in the previous example, it 
is illegal. This is because of left-to-right operator precedence; the assembler attempts to 
add intern_1 to extern_1. 

MOV intern_l + extern_l - intern_2, R4 ; (illegal) 
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3.9 Source Listings 

A source listing shows source statements and the object code they produce. To obtain a 
listing file, invoke the assembler with the -I (lowercase “L") option. 

At the top of each source listing page are two banner lines, a blank line, and a title line. Any 
title supplied by a .title directive is printed on this line; a page number is printed to the right of 
the title. If you don't use the .title directive, the title area is left blank. The assembler inserts a 
blank line below the title line. 

Each line in the source file may produce a line in the listing file that shows a source 
statement number, an SPC value, the object code assembled, and the source statement. A 
source statement may produce more than one byte of object code and may be listed on 
more than one line. If so, each additional line is listed immediately following the source 
statement line. 

Field 1 Source Statement Number 
Line Number 

The source statement number is a decimal number. The assembler numbers 
source lines as it encounters them in the source file; some statements 
increment the line counter but are not listed. (For example, .title statements and 
statements following a .nolist are not listed.) The difference between two 
consecutive source line numbers Indicates the number of statements in the 
source file that are not listed. 

Include File Letter 

The assembler may precede a line with a letter; the letter indicates that the line 
is assembled from an include file. 

Nesting Level Number 

The assembler may precede a line with a number; the number indicates the 
nesting level of macro expansions and loop blocks. 

Field 2 Section Program Counter 

This field contains the section program counter (SPC) value (hexadecimal). All 
sections (.text, .data, .bss, and named sections) maintain separate SPCs. Some 
directives do not affect the SPC; they leave this field blank. 

Field 3 Object Code 

This field contains the hexadecimal representation of the object code. All 
machine instructions and directives use this field to list object code. This field 
also contains two columns immediately preceding the object code, which 
indicate additional information about the line of object code. 

The first column either will be blank or will contain an asterisk (*). The asterisk 
indicates that the object code Is not a direct mapping from the assembly 
source. 
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The second column indicates a relocation type that is associated with one of 
the operands for this line of source code. If more than one operand is 
relocatable, this column Indicates the relocation type for the first one. The 
characters that may appear in this column and their associated relocation types 
are illustrated in the following table; 

! external reference (global) " .data relocatable 

’ text relocatable - .bss, .usect relocatable 

+ .sect relocatable 

Field 4 Source Statement Field 

This field contains the characters of the source statement as they were scanned 
by the assembler. The assembler accepts a maximum line length of 200 
characters. Spacing in this field is determined by the spacing in the source 
statement. 
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Example of an assembler listing with each of the four fields identified: 



1 




.global func3 



2 

0000 



.bss datal,l 



3 

/] 

0001 



.bss data2,1 



5 




.copy "macl.inc" 



1 



add2 

.macro src, dost 



2 




mov src, R4 



3 




mov R4, R5 



4 




mov dest, R4 



5 




add R5,R4 



6 




mov R4, dest 



7 




. endm 



9 




,'k'k'k-k-k-k'k-k-k-k-k'k'k'k'k-ki<-k'k'k'k-ki<i<-k'k'k'k-k'k'k'k 



10 




interrupt vectors ** 



11 







12 

0000 



.sect "int vecs" 



13 

0000 

■ 0000 


.word fund 



14 

0002 

+ 0000 


.word func2 



15 

0004 

lOOOO 


.word func3 



16 







17 




^■k'k-k'k-k'k'k'k'k'k-k'k-k-k'k-k'k'k'k-k'k-k-k'k-k-k-k'k-k'k'k'k 



18 




;** .text section ** 



19 




.******************************** 



20 

0000 



. text 



21 

0000 


fund : 




22 

0000 



add2 datal, data2 


1 


0000 

-40140000 


mov datal, R4 


1 


0004 

4405 


mov R4, R5 


1 


0006 

-4014fff9 


mov data2, R4 


1 


000a 

5504 


add R5,R4 


1 


000c 

-4480fff3 


mov R4, data2 



33 

0020 

-40140000 


mov datal, R4 



34 

0024 

940a 


cmp R4,R10 



35 

0026 

■3401 


jge lab 



36 

0028 

4304 


dr R4 



37 

002a 

1300 

lab: 

reti 



38 







39 

0000 



.sect "other_code" 



40 

0000 

9405 

func2 

cmp R4,R5 



41 

^ 

0002 

^ ^ 

^ 1300 


reti 





'''' T ^ 


T 



Field 1 

Field 2 

Field 3 


Field 4 



Example 3.1: An Assembler Listing 
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3.10 Cross-Reference Listings 

A cross-reference listing shows symbols and their definitions. To obtain a cross-reference 
listing, invoke the assembler with the -x option or use the .option directive. The assembler 
will append the cross-reference to the end of the source listing. 


LABEL 

VALUE 

DEFN 

REF 


datal 

,.0000 

2 

27 

28 

data2 

0001 

3 

27 

27* 

fund 

0000 

26 

18 


func2 

0000 + 

40 

19 


func3 

REF 


1 

20 

lab 

002a 

37 

35 



Example 3.2: An Assembler Cross-Reference Listing 


LABEL column contains each symbol that was defined or referenced during the 

assembly. 

VALUE column contains a 4-digit hexadecimal number, which is the value 

assigned to the symbol ora name that describes the symbol's attributes. A 
value may also be preceded by a character that describes the symbol's 
attributes. The next table lists these characters and names. 


DEFINITION (DEFN) column contains the statement number that defines the symbol. 
This column is blank for undefined symbols. 

REFERENCE (REF) column lists the line numbers of statements that reference the 
symbol. If the line number is followed by an asterisk (*), that reference may 
modify the contents of the object. A blank in this column indicates that the 
symbol was never used. 


Character or Name 

Meaning 

REF 

External reference (global symbol) 

UNDF 

Undefined 


Symbol defined in a .text section 

" 

SyrQbol defined in a .data section 

+ 

Symbol defined in a .sect section 

- 

Symbol defined in a .bss or .usect section * 


Table 3.3: Symbol Attributes 
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4 Assembler Directives 

Assembler directives supply program data and control the assembly process. Assembler 
directives enable you to do the following: 

• Assemble code and data into specified sections 

• Reserve space in memory for uninitialized variables 

• Control the appearance of listings 

• Initialize memory 

• Assemble conditional blocks 

• Define global variables 

• Specify libraries that the assembler can obtain macros from 

• Generate symbolic debugging information 
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4.1 Directives Summary 

The table summarizes the assembler directives. Note that all source statements that contain 
a directive may have a label and a comment To improve readability, they are not shown as 
part of the directive syntax. 


Directives That Define Sections 


Mnemonic and Syntax 

Description 

.bss symbol [, size in bytes, address] 

Reserve size bytes in the .bss 
(uninitialized data) section 

.data [address] 

Assemble into the .data (initialized data) 
section 

.sect “section name"l address] 

Assemble into a named (initialized) section 

.text [address] 

Assemble into the .text (executable code) 
section 

symbol .used “section name", size in bytes 
[, address] 

Reserve size bytes in a named 
(uninitialized) section 


Directives That Initialize Constants (Data and Memory) 
Mnemonic and Syntax __ Description 


.byte value 1 [,..., valuen] 

Initialize one or more successive bytes in 
the current section 

.double floating point value 

Initialize a 48-bit MSP430 floating-point 
constant 

.field value [, size in bits] 

Initialize a variable-length field 

.float floating point value 

Initialize a 32-bit, MSP430 floating-point 
constant 

.space size in bytes 

Reserve size bytes in the current section; 
note that a label points to the beginning of 
the reserved space 

.string “stringi "[,..., “stringn'] 

Initialize one or more text strings 

.word value 1 valuen] 

Initialize one or more 16-bit integers 


Table 4.1: Assembler Directives Summary 
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Directives That Align the Section Counter (SPC) 


Mnemonic and Syntax 

Description 

.align 

Align the SPC on a byte boundary 

.even 

Align the SPC on a word boundary 


Directives That Format the Output Listing 

Mnemonic and Syntax 

Description 

.fclist 

Allow false conditional code block listing (default) 

.fcnolist 

Inhibit false conditional code block listing 

.length page iength 

Set the page length of the source listing 

.list 

Restart the source listing 

.mlist 

Allow macro listings and loop blocks (default) 

.mnolist 

Inhibit macro listings and loop blocks 

.nolist 

Stop the source listing 

.option {AiBiFiMiTiWIXj 

Select output listing options 

.page 

Eject a page in the source listing 

.sslist 

Allow expanded substitution symbol listing 

.ssnolist 

Inhibit expanded substitution symbol listing 
(default) 

.title “string" 

Print a title in the listing page heading 

.width page width 

Set the page width of the source listing 


Table 4.1: Assembler Directives Summary (Continued) 
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Directives That Reference Other Files 


Mnemonic and Syntax 

Description 

.copy [“]filename['] 

Include source statements from another file 

.def symbol-I symboln] 

Identify one or more symbols that are defined in 
the current module and used in other modules 

.global symbol 1 symboln] 

Identify one or more global (external) symbols 

.include [“]f/7er?aAr7e["] 

Include source statements from another file 

.mlib nfilenamei'] 

Define macro library 

.ref symbol-! ^ symboln] 

Identify one or more symbols that are used in 
the current module but defined in another 
module 

Conditional Assembly Directives 

Mnemonic and Syntax 

Description 

.break [well-defined expression] 

Optional repeatable block assembly 

.if well-defined expression 

Begin conditional assembly 

.else 

, Optional conditional assembly 

.elseif well-defined expression 

I 

Optional conditional assembly 

.endif 

End conditional assembly 

.endloop 

End repeatable block assembly 

.loop [well-defined expression] 

I Begin repeatable block assembly 


Table 4.1: Assembler Directives Summary (Continued) 
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Assembly-Time Symbols 


Mnemonic and Syntax 

Description 

.asg [“] character string ['], substitution 

Assign a character string to a substitution 
symbol 

.endstruct 

End structure definition 

■equ 

Equate a value with a symbol 

.eval well-defined expression, sub¬ 

Perform arithmetic on numeric substitution 

stitution symbol 

symbols 

.newblock 

Undefine local labels 

.set 

Equate a value with a symbol 

.struct 

Begin structure definition 

.tag 

Assign structure attributes to a label 

Miscellaneous Directives 

Mnemonic and Syntax 

Description 

.emsg string 

Send user-defined error messages to the output 
device 

.end 

Program end 

.label “symbol" 

Define a load address label 

.mmsg string 

Send user-defined messages to the output 
device 

.setsect “section name",addr 

Produced by absolute lister, See Chapter 9 

symbol .setsym addr 

Produced by absolute lister, See Chapter 9 

.wmsg string 

Send user-defined warning messages to the 
output device 


Table 4.1: Assembler Directives Summary (Concluded) 
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4.2 Directives That Define Sections 

Five directives associate the various portions of an assembly language program with the 
appropriate sections: 

• .bss reserves space in the .bss section for uninitialized variables. 

• .data identifies portions of code in the .data section. The .data section usually contains 
initialized data. 

• .sect defines initialized named sections and associates subsequent code or data with 
that section. A section defined with .sect can contain code or data. 

• .text identifies portions of code in the .text section. The .text section usually contains 
executable code. 

• .usect reserves space in an uninitialized named section. The .usect directive is similar to 
the .bss directive, but it allows you to reserve space separately from the .bss section. 

The output listing on the next page shows how you can use sections directives to associate 
code and data with the proper sections. Column 1 shows line numbers, and column 2 shows 
the SPC values. (Each section has its own program counter, or SPC.) When code is first 
placed in a section, its SPC equals 0. When you resume assembling into a section, its SPC 
resumes counting as if there had been no intervening code. 

After the code in is assembled, the sections contain: 

.text Initializes bytes with the values 1,2, 3, 4, 5, 6, 7, and 8 

.data Initializes bytes with the values 9, 10, 11, 12, 13, 14, 15, and 16 

var_defs Initializes bytes with the values 17 and 18 
.bss Reserves 1 9 bytes 

xy Reserves 20 bytes 

Note that the .bss and .usect directives do not end the current section or begin new sections; 
they reserve the specified amount of space, and then the assembler resumes assembling 
code or data into the current section. 
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2 



;* Start assembling 

into .text 

* 


3 



. 'k'k'k'k'k'k'k'k-k'k-k'kic-k'k-kic'k-k 

'k'k-k-k'k'k'k'k-k'k'k 

* * * * 


4 

0000 


. text 




b 

0000 

01 

.byte 1,2 





0001 

02 





6 

0002 

03 

.byte 3,4 




7 

8 

0003 

04 

. ■k'k'k-k-k'kic-k'ki^'k'kic-k-k'k-k-k'k 

'k-k'ki^'k'kick-k-k-k 

* * * * 


9 



;* Start assembling 

into .data 

* 


10 



. •kic-k'k-k-k'k'kic-k'k'kicic'k-kic'k-k 

i^'k-k'k'k'k'k'k-k-k'k 

* * * * 


11 

0000 


. data 




12 

0000 

09 

.byte 9,10 





0001 

Oa 





13 

0002 

Ob 

.byte 11,12 





0003 

Oc 





14 







15 



. ******************* 

ic-k'k'k'k'k'k'k'k'kic 

* * * * 


16 



;* Start assembling 

into named 

* 


17 



;* section, var_defs 


* 


18 



. ******************* 

*********** 

* * * * 


19 

0000 


.sect "var_def 

s" 



20 

0000 

11 

.byte 17,18 





0001 

12 





21 

22 



.******************* 

*********** 

**** 


23 



;* Resume assembling 

into .data 

* 


24 



******************** 

'kii'k'k'k'k'k'k'k'k'k 

**** 


25 

0004 


. data 




26 

0004 

Od 

.byte 13,14 





0005 

Oe 





27 

0000 


.bss sym,19 

; reserve 

space in 

.bss 

28 

0006 

Of 

.byte 15,16 

; still in 

. data 



0007 

10 





29 







30 



. 'k'k'k'k'k'k'k-kic'k-kic'k'k'k'kic'kic 

*********** 



31 



;* Resume assembling 

into .text 

* 


32 



. ******************* 

*********** 



33 

0004 


. text 




34 

0004 

05 

.byte 5,6 





0005 

06 





35 

0000 


usym .usect "xy",20 

; reserve 

space in 

xy 

36 

0006 

07 

.byte 7,8 

; still in 

. text 



0007 

08 





Example 4.1 

: Sections Directives 
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4.3 Directives That Initialize Memory 

Several directives initialize memory: 

• .byte places one or more 8-bit values into consecutive bytes of the current section. 

• .word places one or more 16-bit values into consecutive bytes in the current section. 

• .string places 8-bit characters from one or more character strings into the current 
section. This directive is identical to .byte. 

• .float calculates a (32-bit) MSP430 floating-point representation of a single precision 
floating-point value and stores it in four consecutive bytes in the current section. 

• .double calculates a (48 bit) MSP430 floating-point representation of a double precision 
floating-point value and stores it in six consecutive bytes in the current section. 

The following code has been assembled for the example, that compares the .byte, .float, 
.word, and .string directives: 


1 

0000 

aa 

.byte OAAh, OBBh 


0001 

bb 


2 

0002 

1234 

.word 01234h 

3 

0004 

68 

.string "help" 


0005 

65 



0006 

6c 



0007 

70 


4 

0008 

81490fdb 

.float 3.141592654 

5 

OOOC 

81490fdaa292 

.double 3.141592654 


Note: How the .byte, .word, .string, .float, .double and .field Directives 

Function in a .struct/.endstruct Sequence 

The .byte, .word, .string, .float, .double and .field directives do not initalize memory when 
they are part of a .struct/.endstruct sequence; rather, they define a member's size. 
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BYTE 




CODE 


7 

0 

7 

0 


0,1 


U] 

[H 


.byte OAAh, OBBh 


7 

0 

7 

0 


2,3 

j_ 

U] 

□I 


.word01234h 


7 

0 

7_ 

0 


4,5 

6 

8 1 


5 

.string "help" 

6,7 

LL 

c 1 

Li_ 

0 



7 

0 

7 

0 


8,9 

r8~ 

1 1 

1 4 

9 

.float 3.141592654 

10,11 

1 0 

F 1 

ID 

~b1 


7 _ 

_c 

7 _ 

_q 


12,13 

_S_ 


4 

9 

.double 3.141592654 

14,15 

JL_ 

F 

_D_ 

_A. 


16,17 

A 

2 

9 

2 



Example 4.2: Initialization Directives 

• The .field directive places a single value into a specified number of bits in the current 
byte. With a field, you can pack multiple fields into a single byte; the assembler does not 
increment the SPC until a byte is filled. 

The next example shows how fields are packed into a byte. For this example, assume 
the following code has been assembled; note that the SPC doesn't change. (The fields 
are packed into the same byte.) 


1 

0000 

03 

.field 

3,3 

2 

0000 

23 

.field 

4,3 

3 

0000 

63 

.field 

1,2 


7 0 



Example 4.3: The .field Directive 

• The .space directive reserves a specified number of bytes in the current section. The 
assembler fills these reserved bytes with Os. 

When you use a label with .space, it points to the first byte of the reserved block. 
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The following code has been assembled for the example of the .space directive: 


45 

0000 

0100 

.word 10Oh,20Oh 


0002 

0200 


46 

0004 


Res_l: .space 17 

47 

0016 

OOOf 

.word 15 


Res_1 points to the first byte in the space reserved by .space. 
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Example 4.4: The .space Directive 
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4.4 Directives That Align the Section Program Counter 

• The .align directive aligns the SPC at the next byte boundary. This directive is useful 
with the .field directive when you do not wish to pack two adjacent fields in the same 
byte. The following code has been assembled for the example: 

1 0000 03 .field 3,3 

2 .align 

3 0001 07 .field 7,4 

4 



Example 4.5: The .align Directive 


• The .even directive aligns the SPC at the next word boundary. It can be used to align 
bytes or strings on word boundaries: 


1 0000 

41 

.string "ABC" 

0001 

42 


0002 

43 


2 


. even 

3 0004 

58 

.string "XYZ" 

0005 

59 


0006 

5a 



4 
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4.5 Directives That Format the Output Listing 

The following directives format the listing file: 

• The source code contains a listing of false conditional blocks that do not generate code. 
The .fclist and .fcnolist directives turn this listing on and off. You can use the .fclist 
directive to list false conditional blocks exactly as they appear in the source code. You 
can use the .fcnolist directive to list only the conditional blocks that are actually 
assembled. 

• The .length directive controls the page length of the listing file. You can use this directive 
to adjust listings for various output devices. 

• The .width directive controls the page width of the listing file. You can use this directive 
to adjust listings for various output devices. 

• The .list and .nolist directives turn the output listing on and off. You can use the .nolist 
directive to prevent the assembler from printing selected source statements in the listing 
file. Use the .list directive to turn the listing back on. 

• The .mlist and .mnolist directives allow and inhibit macro expansion and loop block 
listings. You can use the .mlist directive to print all macro expansions and loop blocks to 
the listing. 

• The .option directive controls several features in the listing file. This directive has several 
operands: 

A Turns on all listing (overrides all other directives and options). 

B Limits the listing of .byte directives to one line. 

F Resets the B, W, M, and T directives. 

M Turns off macro expansions in the listing. 

T Limits the listing of .string directives to one line. 

W Limits the listing of .word directives to one line. 

X Produces a cross-reference listing of symbols. (You can also obtain a cross- 
reference listing by invoking the assembler with the -x option.) 

• The .page directive causes a page eject in the output listing. 

• The .sslist and .ssnolist directives allow and inhibit substitution symbol expansion 
listing. These directives are useful for debugging substitution symbols outside of macros. 

• The .title directive supplies a title that the assembler prints at the top of each page. 
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4.6 Directives That Reference Other Files 

These directives supply information for or about other files: 

• The .copy and .include directives tell the assembler to begin reading source statements 
from another file. When the assembler finishes reading the source statements in the 
copy/include file, it resumes reading source statements from the current file. The 
statements read from a copied file are printed in the listing file; the statements read from 
an included file are not printed In the listing file. 

• The .global directive declares a symbol to be external so that it is available to other 
modules at link time. This directive does double duty, acting as a .def for defined symbols 
and as a .ref for undefined symbols. Note that the linker will resolve an undefined global 
symbol only if it is used in the program. The .global directive declares a symbol as 16 
bits. 

• The .def directive identifies a symbol that is defined in the current module and can be 
used by other modules. The assembler puts the symbol in the symbol table. 

• The .ref directive identifies a symbol that is used in the current module but defined in 
another module. The assembler marks the symbol as an undefined external symbol and 
puts it in the object symbol table so that the linker can resolve its definition. 

• The .mlib directive supplies the assembler with the name of an archive library that 
contains macro definitions. When the assembler encounters a macro that is not defined 
in the current module, it searches for it in the macro library specified with .mlib. 
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4.7 Conditional Assembly Directives 

Conditional assembly directives enable you to instruct the assembler to assemble certain 
sections of code according to a true or false evaluation of an expression. Two sets of 
directives allow you to assemble conditional blocks of code: 

• The .if/.elseif/.else/.endif directives tell the assembler to conditionally assemble a block 
of code according to the evaluation of an expression. 

.if expression Marks the beginning of a conditional block and assembles code if 

the .if condition is true. 

.elseif expression Marks a block of code to be assembled if .if is false and .elseif is 
true. 

.else Marks a block of code to be assembled if .if is false. 

.endif Marks the end of a conditional block and terminates the block. 

• The .loop/.break/.endloop directives tell the assembler to repeatedly assemble a block 
of code according to the evaluation of an expression. 

.loop expression 
.break expression 

.endloop 

The assembler supports 
expressions. 


Marks the beginning a repeatable block of code. 

Continue to repeatedly assemble when the .break expression is 
false. Go to code immediately after .endloop if expression is true. 
Marks the end of a repeatable block, 
several relational operators that are especially useful for conditional 
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4.8 Assembly-Time Symbol Directives 

These directives equate meaningful symbol names to constant values or strings. 

• The .set and .equ directives set a constant value to a symbol. The symbol is stored in the 
symbol table and cannot be redefined; for example: 

bval .set OlOOh 

.word bval, bval*2, bval+12 
br bval 

Note that the .set and .equ directives produce no object code. 

• The .struct/.endstruct directives set up C-like structure definitions, and the .tag 
directive assigns the C-like structure characteristics to a label. 

The .struct./endstruct directives enable you to set up a C-like structure definition so that 
similar elements can be grouped together. Element offset calculation is then left up to the 
assembler. The .struct/.endstruct directives do not allocate memory. They simply create a 
symbolic template that can be used repeatedly. 

The .tag directive assigns structure characteristics to a label. This simplifies the symbolic 
representation and also provides the ability to define structures that contain other 
structures.The .tag directive does not allocate memory, and the structure tag (stag) must 
be defined before it is used. 

type .struct ; structure tag definition 

X .byte 

y .byte 

t_len .endstruct 

coord .tag type ; declare coord (coordinate) 

.usect coord,t_len ;actual?memory?allocation 

add coord.y,R4 

• The .asg directive assigns a character string to a substitution symbol. The value is stored 
in the substitution symbol table. When the assembler encounters a substitution symbol, it 
replaces the symbol with its character string value. Substitution symbols can be 
redefined. 

.asg "10, 20, 30, 40", coefficients 

.byte coefficients 

• The .eval directive evaluates an expression, translates the results into a character string, 
and assigns the character string to a substitution symbol. This directive is most useful for 
manipulating counters; for example: 

.asg 1 , X 
. loop 

.byte x*10h 
.break x = 4 
.eval x+1, X 
.endloop 
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4.9 Miscellaneous Directives 

This section discusses miscellaneous directives. 

• The .setsect directive is generated by the absolute lister. It specifies an absolute starting 
address for a section name so that the assembler can generate an absolute listing. 

• The .setsym directive is generated by the absolute lister. It specifies an absolute address 
for a global symbol. This allows the assembler to generate an absolute listing. 

• The .end directive terminates assembly. It should be the last source statement of a 
program. This directive has the same effect as an end-of-file. 

• The .label directive defines a special symbol that refers to the loadtime address rather 
than the runtime address within the current section. 

These three directives enable you to define your own error and warning messages: 

• The .emsg directive sends error messages to the standard output device. The .emsg 
directive generates errors in the way the assembler does, incrementing the error count 
and preventing the assembler from producing an object file. 

• The .wmsg directive sends warning messages to the standard output device. The .wmsg 
directive functions in the same way the .emsg directive does, but increments the warning 
count and does not prevent the assembler from producing an object file. 

• The .mmsg directive sends assembly-time messages to the standard output device. The 
.mmsg directive functions in the same way the .emsg and .wmsg directives do, but does 
not set the error count or the warning count and does not prevent the assembler from 
producing an object file. 
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4.10 Directives Reference 

The remainder of this chapter is a reference. Generally, the directives are organized 
alphabetically, one directive per page; related directives (such as .if/.else/.endif), however, 
are presented together on one page. Here's an alphabetical table of contents for the 
directives reference: 


Directive 

.align. 

■asg. 

.break. 

.bss. 

.byte. 

.copy. 

.data. 

.double.... 
.def. 

.elseif. 

.else. 

.emsg. 

.end. 

.endif. 

.endloop.. 
.endstruct 

.equ. 

.eval. 

.even . 

.fclist. 

.fcnolist.... 

.field. 

.float. 

.global. 

.if. 

.include.... 

.label. 

.length. 

.list. 

.loop. 

.mlib. 

.mlist. 

.mmsg. 

.mnolist.... 


Page Directive Page 

..4-20 

..4-21 .newblock.4-51 

..4-46 .nolist.4-44 

..4-23 .option.4-52 

..4-24 .page.4-54 

..4-25 .ref.4-37 

..4-27 

..4-28 .sect.4-55 

..4-37 .set.4-56 

.space.4-58 

..4-40 .sslist.4-59 

..4-40 .ssnolist.4-59 

..4-29 .string.4-24 

..4-30 .struct.4-61 

..4-40 

..4-46 .tag.4-61 

..4-61 .text.4-63 

..4-56 .title.4-64 

..4-21 .usect.4-65 

..4-31 .width.4-43 

.wmsg.4-29 

..4-32 .word.4-67 


.4-32 

.4-33 

.4-36 

.4-37 

.4-40 

.4-25 

.4-42 

.4-43 

.4-44 

.4-46 

.4-48 

.4-50 

.4-29 

.4-50 
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Syntax .align 

Description The .align directive aligns the section program counter (SPC) on the 

next byte boundary. This directive is useful with the .field directive 
when you do not wish to pack two adjacent fields in the same byte. 

Example This example shows the creation of two fields that would normally be 

packed within the same byte. The .align directive forces these fields 
into separate bytes. 

1 0000 03 .field 3,3 

2 .align 

3 0001 07 .field 7,4 

4 



4-21 










Assembler Directives 


MSP430 Family 


Syntax 

Description 


.asg [ " ] character string " ], substitution symbol 

.eval well-defined expression, substitution symbol 

The .asg directive assigns character strings to substitution symbols; 
substitution symbols are stored in the substitution symbol table. 

The .asg directive can be used in many of the same ways as the .set 
directive, but while .set assigns a constant value (cannot be redefined) 
to a symbol, .asg assigns a character string (can be redefined) to a 
substitution symbol. 

• The assembler assigns the character string to the substitution 
symbol. The quotation marks are optional. If there are no quotation 
marks, the assembler reads characters up to the first comma and 
removes leading and trailing blanks. In either case, a character 
string is read and assigned to the substitution symbol. 

• The substitution symbol Is a required parameter that must be a 
valid symbol name. The substitution symbol may be 32 characters 
long and must begin with a letter. Remaining characters of the 
symbol can be a combination of alphanumeric characters, under¬ 
scores, and dollar signs. 

The .eval directive performs arithmetic operations on substitution 
symbols. This directive evaluates the expression and assigns the 
string value of the result to the substitution symbol. The .eval directive 
is especially useful as a counter in .loop/.endloop blocks. 
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Example 


This example shows how .asg and .eval can be used. 


1 


•sslist; show 

expanded sub.syms 

2 

. * 




3 

; * 

.asg/.eval example 


4 

; * 




5 


. asg 

&, AND 

6 


. asg 

Rll, 

FP 

7 





8 

0000 503b000c 

add 

#32 . 

AND 44, FP 

# 


add 

#32 , 

Sc 44, Rll 

9 





10 


. asg 

0, X 


11 


. loop 

5 


12 


. eval 

x+1, 

X 

13 


.word 

X 


14 


.endloop 


1 


. eval 

x+1, 

X 

# 


. eval 

0 + 1, 

X 

1 

0004 0001 

.word 

X 


# 


.word 

1 


1 


. eval 

x+1, 

X 

# 


. eval 

1+1, 

X 

1 

0006 0002 

.word 

X 


# 


.word 

2 


1 


. eval 

x+1. 

X 

# 


. eval 

2 + 1, 

X 

1 

0008 0003 

.word 

X 


# 


.word 

3 


1 


. eval 

x+1. 

X 

# 


. eval 

3 + 1, 

X 

1 

000a 0004 

.word 

X 


# 


.word 

4 


1 


. eval 

x+1, 

X 

# 


. eval 

4 + 1, 

X 

1 

000c 0005 

.word 

X 


# 


.word 

5 
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Syntax 

Description 


Exampie 


.bss name [, size in bytes, address] 

The .bss directive reserves space in the .bss section for variables. Use 
this directive to allocate space into RAM. 

• The name is a required parameter. It defines a symbol that points 
to the first location reserved by the directive. 

• The size is an optional parameter. It is a well-defined, absolute 
expression that specifies the number of bytes that are allocated. 
The default size for this directive is 1 byte. 

• The address is an optional parameter that specifies a 16-bit 
address. It can be used only the first time a .bss directive is 
specified. Normally, the SPC is set to 0 the first time a named 
section is assembled; you can use the address parameter to 
assign an initial value to the SPC. This parameter has no effect on 
the final address of the section. 

Section directives for initialized sections (.text, .data, and .sect) end 
the current section and begin assembling into another section. Section 
directives for uninitialized sections (.bss, .reg, .regpair, and .usect), 
however, do not affect the current section. The assembler assembles 
the .bss, .reg, .regpair, or .usect directive and then resumes 
assembling code Into the same section. 

This example shows the .bss directive used to allocate space for two 
variables, array and dflag. The symbol array points to 100 bytes of 
uninitialized space (at .bss-SPC = 0). The symbol dflag points to 1 
byte of uninitialized space (at .bss-SPC = 100). Note that symbols 
declared with the .bss directive can be referenced in the same manner 
as other symbols and can also be declared global. 


1 

2 

3 

4 0000 

5 0000 

6 

7 

8 
9 

10 0000 
11 0002 
12 

13 

14 

15 

16 0064 

17 0004 

18 

19 

20 
21 


;* Begin assembling into .text * 

. text 

4a0b mov RlO, Rll 


4b0c 


*r**************************** 

* Allocate 100 bytes in .bss 


.bss array,100 

mov Rll, R12 ; assembled into .text 


;* Allocate 1 byte in .bss * 

.bss dflag 

-4014005e mov dflag,R4 /assembled into .text 


.*************************************** 
;* Declare external .bss symbol * 
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22 


.global array ; still 


. text 
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Syntax 


Description 


Exampie 


.byte value-f valuef^] 

.string value-/ valuen] 

The .byte and .string directives place one or more 8-bit values into 
consecutive bytes of the current section. A value can be either: 

• An expression that the assembler evaluates and treats as an 8-bit 
signed number, or 

• A character string enclosed in double quotes. Each character in a 
string represents a separate value. 

The assembler truncates values that are greater than 8 bits. You can 
use up to 100 value parameters, but the total line length cannot 
exceed 200 characters. 


If you use a label, it points to the location at which the assembler 
places the first byte. 

Note that when you use .byte or .string in a .struct/.endstruct 
sequence, .byte or .string defines a member's size; it does not initialize 
memory. 


This example shows several 8-bit values placed into consecutive 
bytes in memory. The label strx has the value Oh, which is the location 
of the first initialized byte. The label stry has the value 6h, which is the 
first byte initialized by the .string directive. 


0000 

Oa 

0001 

ff 

0002 

61 

0003 

62 

0004 

63 

0005 

61 

0006 

Oa 

0007 

ff 

0008 

61 

0009 

62 

000a 

63 

000b 

61 


strx .byte 10,-1,"abc",'a' 


stry .string 10,-1,"abc",'a' 
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Syntax 


Description 


.copy [ "]filename[ "] 

.include [ "]filenam^ "] 

(The quote marks surrounding the filename are optional.) 

The .copy and .include directives tell the assembler to read source 
statements from a different file. The assembler: 

1) Stops assembling statements in the current source file. 

2) Assembles the statements in the copied/included file. 

3) Resumes assembling statements in the main source file, starting 
with the statement that follows the .copy or .include directive. 

The filename is a required parameter that names a source file; the 
filename may be enclosed in double quotes. The filename must follow 
operating system conventions. You can specify a full pathname (for 
example, c:\430\file1.asm). If you do not specify a full pathname, the 
assembler searches for the file in; 

1) The directory that contains the current source file. 

2) Any directories named with the -i assembler option. 

3) Any directories specified by the environment variable A_DIR. 

The statements that are assembled from a copy file are printed in the 
assembly listing. The statements that are assembled from an included 
file are not printed in the assembly listing, regardless of the number of 
.list/.nolist directives that are assembled. 

The .copy and .include directives can be nested within a file being 
copied or included. The assembler limits this type of nesting to eight 
levels; the host operating system may set additional restrictions. The 
assembler precedes the line numbers of copied files with a letter code 
to identify the level of copying. An A indicates the first copied file, B 
indicates a second copied file, etc. 
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Example 1 This example shows how the .copy directive is used to tell the 

assembler to read and assemble source statements from other files, 
then to resume assembling into the current file. 


copy.asm 

byte.asm 

word.asm 

(source file) 

(first copy file) 

(second copy file) 

.space 29 

**In byte.asm 

** In word.asm 

.copy "byt e.asm" 

.byte 32,1+'A' 

.word OABCDh, 56q 


.copy "word.asm" 


**Back in original file 

** Back in byte.asm 


•String "done" 

.byte 67h+3q 


Listing file: 



1 0000 

.space 29 


2 

.copy "byte.asm" 

A 

1 

** In byte.asm 

A 

2 OOld 20 

.byte 32,1+'A' 


OOle 42 


A 

3 

.copy "word.asm" 

B 

1 

** In word.asm 

B 

2 0020 abed 

.word OABCDh, 56q 


0022 002e 


A 

4 

** Back in byte.asm 

A 

5 0024 6a 

.byte 67h+3q 


4 

c: 

** Back in original file 


D 

6 0025 64 

.string "done" 


0026 6f 



0027 6e 



0028 65 



Example 2 This example shows how the .include directive is used to tell the 

assembler to read and assemble source statements from other files, 
then to resume assembling into the current file. 


include.asm 
(source file) 

byte2.asm 
(first include file) 

word2.asm 
(second include file) 

.space 29 

** In byte2.asm 

** In word2.asm 

.include "byte2.asm" 

.byte 32,1+ 'A' 

.include "word2.asm" 

.word OABCDh, 56q 

**Back in original file 

** Back in byte.asm 


.string "done" 

.byte 67h+3q 



Listing file: 


1 

0000 


.space 29 

2 



.include "byte2.asm 

3 




4 



;**Back in original 

5 

0025 

64 

.string "done" 


0026 

6f 



0027 

6e 



0028 

65 
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Syntax 

Description 


Example 


.data [address] 

The .data directive tells the assembler to begin assembling source 
code into the .data section; .data becomes the current section. The 
.data section is normally used to contain tables of data or preinitialized 
variables. 

The address is an optional parameter that specifies a 16-bit address. 
It can be used only the first time a .data directive is specified. 
Normally, the section program counter is set to 0 the first time the .data 
section is assembled; you can use this parameter to assign an initial 
value to the .data section program counter. This parameter has no 
effect on the final address of the section; it simply makes the listing 
easier to read. 

Note that the assembler assumes that .text is the default section. 
Therefore, at the beginning of an assembly, the assembler assembles 
code into the .text section unless you specify an explicit section control 
directive. 

This example shows the assembly of code into the .data and .text 
sections. 


1 



.-k'k-k'kic'k-k'k'k'k-^'kic-k'kicicic-k-k-k-kic'k'k-k-k-k'k'k'k-k-k-k-k-k 

2 



Reserve space in .data ** 

3 



,'k-k'k'k-k'k-k'k'k-k'k'k-k'k-k'k‘kic-k'k-k-k^-ki<'k-^-^-^'k‘k'k'k-:hic'k 

4 

0000 


. data 

5 

6 

0000 


.space Occh 

7 



.************************************ 

8 



Assemble into .text ** 

9 



.************************************ 

10 

0000 


. text 

11 


00 

Index .equ 0 

12 

0000 

4304 

mov #Index, R4 

13 




14 



,'k'k'k'k'kic'k-k'k-k'k-k-k'k-k'ki<'ki('k-k-k-k'k‘k-ki(i<'k'k'ki<'k'k-k-k 

15 



Assemble into .data ** 

16 




17 

OOcc 


Table: .data 

18 

OOcc 

ffff 

.word -1 

19 

OOce 

ff 

.byte Offh 

20 




21 



.************************************ 

22 



;** Assemble into .text ** 

23 



.******************************■****** 

24 

0002 


. text 

25 

0002 

’■901400C8 

cmp Table, R4 

26 




27 



.*********************************-*** 

28 



;** Resume Assembling into .data ** 

29 



.************************************ 

30 

OOcf 


. data 
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Syntax 

Description 


Examples 


.double value 

The .double directive places the floating-point representation of a 
double floating-point constant into six bytes in the current section. The 
value must be a floating-point constant. Each constant is converted to 
a floating-point value in the MSP430 (48-bit) format. 

The 48-bit value consists of three fields: 

• An 8-bit biased exponent (e) 

• A 1-bit sign field (s) 

• A 39-bit fraction (f) 

The value is stored exponent byte first, most significant byte of fraction 
second, and least significant byte of fraction sixth in the following 
format: 


47 


40 39 38 


Note that when you use .double in a .struct/.endstruct sequence, 
.double defines a member's size; it does not initialize memory. For 
more information about MSP430 floating-point format, refer to 
Appendix G. 


Here are some examples of the .double directive. 


1 0000 d38459516140 

2 0006 814000000000 

3 000c 8d40e4000000 


•double -1.0e25 
•double 3 
•double 12345 
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Syntax 


Description 


Example 


.emsg string 
.mmsg string 
.wmsg string 

Use these directives to define your own error and warning messages. 
Note that the assembler tracks the number of errors and warnings it 
encounters and prints these numbers on the last line of the listing file. 

• The .emsg directive sends error messages to the standard output 
device. The .emsg directive generates errors in the same way the 
assembler does, incrementing the error count and preventing the 
assembler from producing an object file. 

• The .wmsg directive sends warning messages to the standard 
output device. The .wmsg directive functions in the same way the 
.emsg directive does, but increments the warning count. The 
assembler is not prevented from producing an object file. 

• The .mmsg directive sends assembly-time messages to the 
standard output device. The .mmsg directive functions in the same 
way the .emsg and .wmsg directives do, but does not set the error 
count or the warning count. The assembler is not prevented from 
producing an object file. 

In this example, the message "ERROR - MISSING PARAMETER" is 
sent to the standard output device. 



1 

MSG_EX .macro 

parml 


2 

. if 

$symlen(parml) = 0 


3 

. emsg 

"ERROR -- MISSING PARAMETER" 


4 

. else 



5 

MOV 

parml, A 


6 

.endif 



7 

Q 

. endm 



O 

9 0000 

MSG_EX 


1 


.if 

$symlen(parml) = 0 

1 


. emsg 

"ERROR -- MISSING PARAMETER" 

1 


. else 


1 


MOV 

parml, A 

1 


.endif 



These messages will show in the readout like any other error 
message: 

********* USER ERROR - ERROR -- MISSING PARAMETER 
********* USER WARNING - • • • 

********* USER MESSAGE - • • • 
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Syntax .end 

Description The .end directive is an optional directive that terminates assembly. It 

should be the last source statement of a program. The assembler 
ignores any source statements that follow an .end directive. 

This directive has the same effect as an end-of-file. You can also use 
.end when you're debugging code and you'd like to stop assembling at 
a specific point in your code. 


Note: Use .endm to End a Macro 

Do not use the .end directive to terminate a macro; use the endm 
macro directive instead. 


Exampie This example shows how the .end directive terminates assembly. If 

any source statements follow the .end directive, the assembler ignores 
them. 


1 

0000 


Text_start: 

.text 

2 

0000 

Oa 


.byte Oah 

3 

0002 

aaaa 


.word Oaaaah 

4 

0004 

61 


.string "aaa 


0005 

61 




0006 

61 




5 . end 
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Syntax 

Description 


Example 


.even 

The .even directive aligns the section program counter (SPC) on the 
next word boundary. This directive can be used to force the start of the 
next initialized data on an even address. 


This example shows the initialization of two strings, each aligned on a 
word boundary. Without the .even directive the second string would 
start immediately after the first one (on an odd address). 


1 0000 41 

0001 42 

0002 43 

2 

3 0004 58 

0005 59 

0006 5a 

4 


.string "ABC" 


. even 

.string "XYZ" 


Note: Automatic Alignment on Word Boundary 

Instructions itself and data created by .word, .float and .double directives will be aligned on 
a word boundary automatically. 
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Syntax 

Description 

Exampie 


.fclist 

.fcnoiist 

Two directives enable you to control the listing of false conditional 
blocks. 


• The .fclist directive allows the listing of conditional blocks that do 
not produce code (false blocks). By default, the assembler 
behaves as if you had used .fclist 

• The .fcnoiist directive inhibits the listing of false conditional blocks 
that do not produce code. Only code in the conditional block that 
actually assembles appears in the listing. The .if, .elseif, .else, and 
.endif directives do not appear. 

This example shows the assembly language file and the listing file for 
code with and without the conditional blocks listed. This is the un¬ 
assembled file: 


X .set 1 
y .set 0 

.fclist 

.if X 

MOV #5, 
. else 
MOV #9, 
.endif 


R4 


; True 
;False 


.fcnoiist 


.if X 
MOV #5, 
. else 
MOV #9, 
.endif 


R4 


This is the listing file: 


1 


01 

X 

. set 1 

;' 

2 


00 

y 

. set 0 

;; 

3 






4 




.fclist 


5 






6 




.if X 


7 

0000 

40340005 


MOV #5, 

R4 

8 




. else 


9 




MOV #9, 

R4 

10 




.endif 


11 






12 




.fcnoiist 

13 






15 

0004 

40340005 


MOV #5, 

R4 
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Syntax 

Description 


.field value [, size in bits] 

The .field directive initializes multiple-bit fields within a single word of 
memory. This directive has two operands: 

• The value is a required parameter; it is an expression that is 
evaluated and placed in the field. The value must be absolute. 

• The size is an optional parameter; it specifies a number from 1 to 
16, which is the number of bits the field consists of. If you do not 
specify a size, the assembler assumes that the size is 16 bits. If 
you specify a value that cannot fit in size bits, the assembler 
truncates the value and issues a warning message. For example, 
.field 3,1 causes the assembler to truncate the value 3 to 1; the 
assembler also prints the message: 


***warning - value truncated. 

Successive .field directives pack values into the specified number of 
bits in the current word. Fields are packed starting at the least 
significant part of the word, moving toward the most significant part as 
more fields are added. If the assembler encounters a field size that 
does not fit into the current word, it writes out the word, increments the 
SPC, and begins packing fields into the next word. 

You can use the .align directive to force the next .field directive to 
begin packing into a new byte. 

If you use a label, it points to the word that contains the field. 

Note also that when you use .field in a .struct/.endstruct sequence, 
.field defines a member's size; it does not initialize memory. 
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Example 


This example shows how fields are packed into a word. Note that the 
SPC does not change until a word is filled and the next word is begun. 


1 

2 

3 

4 0000 04de 

5 

6 

7 

8 
9 

10 0000 0b27 

11 
12 

13 

14 

15 

16 0000 5b27 

17 

18 

19 

20 
21 

22 0000 la 


************************************ 

* Initialize a 11-bit field * 
*********************************** 

.field 4deh,ll 

******************************** 

* Initialize a 12-bit field * 

* in a new word * 

.field 0b27h,12 


Initialize a 3-bit field 
in the same byte 

.field 5,3 


******************************** 

* Initialize a 5-bit field * 

* in the next byte * 

******************************** 

.field lah,5 
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The example shows how the directives affect memory. 



Example 4.7: The .field Directive 
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Syntax 

Description 


Exampie 


.float value 

The .float directive places the floating-point representation of a single 
floating-point constant into four bytes in the current section. The value 
must be a floating-point constant. Each constant is converted to a 
floating-point value in MSP430 (32-bit) format. 

The 32-bit value consists of three fields: 

• An 8-bit biased exponent (e) 

• A 1-bit sign field (s) 

• A 23-bit fraction (/) 

The value is stored exponent byte first, most significant byte of fraction 
second, and least significant byte of fraction fourth in the following 
format: 


31 


24 23 22 _0 

e I s I f 


Note that when you use .float in a .struct/.endstruct sequence, .float 
defines a member's size; it does not initialize memory. For more 
information about MSP430 floating-point format, refer to Appendix G. 

Here are some examples of the .float directive. 


1 0000 d3845951 

2 0004 81400000 

3 0008 8d40e400 


.float -1.0e25 
.float 3 
.float 12345 
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Syntax 


Description 


Example 


.global symbol 1 [,..., symbol^] 

.def symbol 1 [,..., symbol^] 

.ref symbol-I symbol^] 

The .global, .def, and .ref directives identify global symbols, which are 
defined externally or can be referenced externally. 

• The .def directive identifies a symbol that is defined in the current 
module and can be accessed by other files. The assembler places 
this symbol in the symbol table. 

• The .ref directive identifies a symbol that is used in the current 
module but defined in another module. The linker resolves this 
symbol's definition at link time. 

• The .global directive acts as a .ref or a .def, as needed. 

A global symbol is defined in the same manner as any other symbol; 
that is, it appears as a label or is defined by the .set, .equ, .bss or 
.usect directive. As with all symbols, if a global symbol is defined more 
than once, the linker issues a multiple-definition error. Note that .ref 
always creates an entry for a symbol, whether the module uses the 
symbol or not; .global, however, create a symbol table entry only if the 
module actually uses the symbol. 

A symbol may be declared global for two reasons: 

1) If the symbol is not defined in the current module (including macro, 
copy, and include files), the .global or .ref directive tells the 
assembler that the symbol is defined in an external module. This 
prevents the assembler from issuing an unresolved reference 
error. At link time, the linker looks for the symbol's definition in 
other modules. 

2) If the symbol is defined in the current module, the .global, .globreg, 
or .def directive declares that the symbol and its definition can be 
used externally by other modules. These types of references are 
resolved at link time. 

This example shows four files; 

• file1.1st and fileS.lst are equivalent. Both files define the symbol Init 
and make it available to other modules; both files use the external 
symbols x, y, and z. filel.lst uses the .global directive to identify the 
global symbols; fileS.lst uses .ref and .def to identify the symbols. 

• file2.lst and flle4.lst are equivalent. Both files define the symbols x, 
y, and z and make them available to other modules; both files use 
the external symbol Init. file2.lst uses the .global directive to 
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identify the nonregister global symbols; file4.lst uses .ref and .def to 
identify the nonregister symbols. 
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filel.lst 

1 


; Global 

2 

3 

4 


; Global 

5 

6 

7 0000 

5034002c 

init: 

8 0004 

10000 


9 


; 

10 


; 

11 


; 

12 




file 2 .lst 


symbol defined in this file 
.global init 

symbols defined in file2.1st 
.global X, y, z 

add #44, R4 
.word X 


. end 


1 

2 

3 

4 

5 

6 

7 

8 
9 

10 0000 
11 
12 
13 
14' 


01 

02 

03 

10000 


; Global symbol defined in this file 
.global X, y, z 

; Global symbols defined in filel.lst 
.global init 

X .equ 1 

y .equ 2 

z .equ 3 

.word init 


. end 
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fileS.lst 

1 

2 

3 

4 

5 

6 

7 0000 5034002c 

8 0004 10000 

9 

10 

11 

12 


; Global symbol defined in this file 
.def init 

; Global symbols defined in file4.1st 
.ref X, y, z 

init: add #44, R4 

.word X 


. end 


file 4 .lst 


1 


; Global 

symbol defined in this file 

2 



.def X, y, z 

3 




4 


; Global 

symbols defined in file3.1s 

5 



.ref init 

6 




7 

01 

X 

. equ 1 

8 

02 

y 

. equ 2 

9 

03 

z 

. equ 3 

10 0000 

! 0000 


.word init 

11 


; 


12 


; 


13 


; 


14 



. end 
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Description 


.if well-defined expression 

code to assemble when the expression is true 

.elseif well-defined expression 

code block to execute when the expression is true 

.else 

code to assemble when the expression is false 

.endif 

terminate condition block 

Four directives provide conditional assembly: 

• The .if directive marks the beginning of a conditional block. The 
expression is a required parameter. 

• If the expression evaluates to true (nonzero), the assembler 
assembles the code that follows it (up to an .elseif, an .else, or 
an .endif). 

• If the expression evaluates to false (0), the assembler 
assembles code that follows an .elseif (if present), an else (if 
present), or an .endif (if no .elseif or .else is present). 

• The .elseif directive identifies a block of code to be assembled 
when the .if expression is false (0) and the .elseif expression is true 
(nonzero). When the .elseif expression is false, the assembler 
continues to the next .elseif (if present), .else (if present), or an 
.endif. The .elseif directive is optional in the conditional block, and 
more than one .elseif can be used. If an expression is false and 
there is no .elseif statement, the assembler continues with the code 
that follows an .else (if present) or an .endif. 

• The .else directive identifies a block of code that the assembler 
assembles when the .if expression is false (0). This directive is 
optional in the conditional block; if an expression is false and there 
is no .else statement, the assembler continues with the code that 
follows the .endif. 

• The .endif directive terminates a conditional block. 

The .elseif and .else directives can be used in the same conditional 
assembly block, and the .elseif directive can be used more than once 
within a conditional assembly block. 
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Example 


Here are some examples of conditional assembly: 


1 

01 

syml 

. set 1 


2 

02 

sym2 

. set 2 


3 

03 

sym3 

. set 3 


4 

04 

sym4 

. set 4 


5 


If_4: 

.if syin4=sym2*sym2 

6 0000 

04 


.byte sym4 

; Equal values 

7 



.else 


8 



.byte sym2 * sym2 

; Unequal values 

9 



.endif 


10 


If_5: 

.if SYinl<=10 


11 0001 

OA 


.byte 10 

; Less than/equal 

12 



.else 


13 



.byte syml 

; Greater than 

14 



.endif 


15 


If_6: 

.if sym3*sym2! = 

sym4+sym2 

16 



.byte sym3*sym2 

;Unequal values 

17 



.else 


18 0002 

06 


.byte sym4+sym2 

;Equal values 

19 



.endif 


20 


1 

H 

.if syml=2 


21 



.byte syml 


22 



.elseif sym2+sym3 

= 5 

23 0003 

05 


.byte sym2+sym3 


24 



.endif 
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Description 


.label symbol 

The .label directive defines a special symbol that refers to the loadtime 
address rather than the runtime address within the current section. 
Most sections created by the assembler have relocatable addresses. 
The assembler assembles each section as if it started at zero, and the 
linker relocates it to the address at which it loaded and ran. 

For some applications, it is desirable to have a section load at one 
address and run at a different address. For example, you may wish to 
load a block of performance-critical code into slower off-chip memory 
to save space, and then move the code to high-speed on-chip 
memory to run it. 

Such a section is assigned two addresses at link time: a load address 
and a separate run address. All labels defined in the section are 
relocated to refer to the runtime address so that references to the 
section (such as branches) are correct when the code runs. 

The .label directive creates a special “label" that refers to the loadtime 
address. This is useful primarily so that the code that relocates the 
section knows where the section was loaded. For example: 


; .label Example 


.sect ".examp" 
.label examp_load 

start: 

<code> 
finish: 

.label examp_end 


; load address of section 
; run address of section 

; run address of section end 
; load address of section end 
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Syntax 

Description 


Example 


.length page length 
.width page width 

The .length directive sets the page length of the output listing file. It 
affects the current page and following pages; you can reset the page 
length with another .length directive. 

• Default length: 60 lines 

• Minimum length: 1 line 

• Maximum length: 32,767 lines 

The .width directive sets the page width of the output listing file. It 
affects the next line assembled and following lines; you can reset the 
page width with another .width directive. 

• Default width: 132 characters 

• Minimum width: 80 characters 

• Maximum width: 200 characters 

Note that the width refers to a full line in a listing file; the line counter 
value, SPC value, and object code are counted as part of the width of 
a line. Comments and other portions of a source statement that extend 
beyond the page width are truncated in the listing. 

The assembler does not list the .width and .length directives. 

The following example shows how to change the page length and 
width. 


********************************************* 
** Page length = 65 lines ** 

** Page width = 85 characters ** 

********************************************* 

.length 65 
.width 85 


********************************************* 
** Page length = 55 lines ** 

** Page width = 100 characters ** 

‘k'k'k'k'k'k'k'kiric'k'k'k'k'k'k'k'k'k'k'ki^'k'kif:'k'ki^ic-k'k'k':k'k'kik'k-k'k-k‘k‘k'k‘k'k 


.length 55 

.width 100 
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Syntax .list 

.nolist 

Description The .nolist directive suppresses the source listing output until a .list 

directive is encountered. The .list directive tells the assembler to 
resume printing the source listing after it has been stopped by a .nolist 
directive. By default, the assembler acts as if a .list directive had been 
specified. The .nolist directive can be used to reduce assembly time 
and the size of the source listing; it can be used in macro definitions to 
inhibit the listing of the macro expansion. 

The assembler does not print the .list or .nolist directives or the source 
statements that appear after a .nolist directive; however, it continues to 
increment the line counter. You can nest the .list/.nolist directives; 
each .nolist needs a matching .list to restore the listing. At the 
beginning of an assembly, the assembler acts as if it has assembled a 
.list directive. 


Note: Creating a Listing Fiie (-i option) 

If you don’t request a listing file when you invoke the assembler, the assembler ignores the 
.list directive. 


Example This example shows how to use the .copy directive to insert source 

statements from another file. The first time this directive is 
encountered, the assembler lists the copied source lines in the listing 
file. The second time this directive is encountered, the assembler does 
not list the copied source lines, because a .nolist directive was 
assembled. Note that the .nolist, the second .copy, and .list directives 
do not appear in the listing file; note also that the line counter is 
incremented even when source statements are not listed. 

Source file: 

.copy "copy2.asm" 

* Back in original file 

.nolist 

.copy "copy2.asm" 

. list 

* Back in original file 

.string "Done" 
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Listing file: 

1 

A 1 


2 

0000 

0020 


0002 

0042 

2 



6 



7 

0008 

44 


0009 

6f 


000a 

6e 


000b 

65 


.copy "copy2.asm" 
In copy2,asm (copy file) 
.word 32, 1+'A' 

Back in original file 
Back in original file 
.string "Done" 
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Syntax 


Description 


.loop [well-defined expression] 
code block to repeatedly assemble 

.break [well-defined expression] 

continue to assemble repeatedly when the .break expression is false 
(zero); go to code immediately following .endloop if expression is true 
(nonzero) 

.endloop 

code block to execute when the .break directive is true (nonzero) or 
when the .break expression is omitted and the loop count equals the 
expression 

Three directives enable you to repeatedly assemble a block of code: 

• The .loop directive begins a repeatable block of code. The optional 
expression evaluates to the loop count. If there is no expression, 
the loop count defaults to 1024, unless the assembler encounters a 
.break directive. 

• The .break directive is optional, along with its expression. When 
the expression is false (0), the loop continues. When the expres¬ 
sion is true (nonzero) or omitted, the assembler breaks the loop 
and assembles the code after the .endloop directive. 

• The .endloop directive terminates a repeatable block of code. 
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Example 


This example illustrates how these directives can be used with the 
.eval directive. 



1 




. eval 

0, X 


2 



coef 

. loop 



3 




.word 

x*100 


4 




. eval 

X+1 , X 


5 




•break 

X = 7 


6 




.endloop 

1 


0000 

0000 


.word 

0*100 

1 





. eval 

0 + 1, X 

1 





.break 

1 = 7 

1 


0002 

0064 


.word 

1*100 

1 





. eval 

1 + 1 , X 

1 





.break 

2 = 7 

1 


0004 

00c8 


.word 

2*100 

1 





. eval 

2 + 1,X 

1 





.break 

3 = 7 

1 


0006 

012c 


.word 

3*100 

1 





. eval 

3 + 1,X 

1 





.break 

4 = 7 

1 


0008 

0190 


.word 

4*100 

1 





. eval 

4 + 1,X 

1 





.break 

5 = 7 

1 


000a 

0114 


.word 

5*100 

1 





. eval 

5 + 1,X 

1 





.break 

6 = 7 

1 


000c 

0258 


.word 

6*100 

1 





. eval 

6 + 1 , X 

1 





.break 

7 = 7 
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Syntax 

Description 


Example 


.mlib [‘]filename['] 

(The quote marks surrounding the filename are optional.) 

The .mlib directive provides the assembler with the name of a macro 
library. A macro library is a collection of files that contain macro 
definitions. These files are bound into a single file (called a library or 
archive) by the archiver. Each member of a macro library may contain 
one macro definition that corresponds to the name of the file. Note 
that: 

• Macro library members must be source files (not object files). 

• The filename of a macro library member must be the same as the 
macro name, and its extension must be .asm. 

The filename must follow host operating system conventions; it may be 
enclosed in double quotes. You can specify a full pathname (for 
example, c:\430\macs.lib). If you do not specify a full pathname, the 
assembler searches for the file in: 

1) The directory that contains the current source file. 

2) Any directories named with the -i assembler option. 

3) Any directories specified by the environment variable A_DIR . 

When the assembler encounters an .mlib directive, it opens the library 
and creates a table of the library's contents. The assembler enters the 
names of the individual library members into the opcode table as 
library entries; this redefines any existing opcodes or macros that have 
the same name. If one of these macros is called, the assembler 
extracts the entry from the library and loads it into the macro table. The 
assembler expands the library entry in the same manner as other 
macros, but it does not place the source code into the listing. Only 
macros that are actually called from the library are extracted, and they 
are extracted only once. 


This example shows how to create a macro library that defines two 
macros, inc1 and dec1. The file ind.asm contains the definition of 
inc1, and dec1 .asm contains the definition of dec1. 


ind.asm 

ded .asm 

* Macro for incrementing 

* Macro for decrementing 

incl .MACRO nam 

decl .MACRO nam 

mov nam, R4 

mov nam, R4 

inc R4 

dec R4 

mov R4, nam 

mov R4, nam 

.ENDM 

.ENDM 
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ar430 -a mac incl.asm decl.asm 

Now you can use the .mlib directive to reference the macro library and 
define the inc1 and dec1 macros; 


1 0000 
2 0001 

3 

4 

5 


1 

6 

0000 

0000 

-40140000 

1 


0004 

5314 

1 


0006 

-44800000 

1 

7 

000a 

000a 

-4014fff5 

1 


OOOe 

8314 

1 


0010 

-4480ffef 


•bss varl,l 

.bss var2,1 

.mlib "mac.lib" 

incl varl ; macro call 

mov varl, R4 

inc R4 

mov R4, varl 

decl var2 ; macro call 

mov var2, R4 

dec R4 

mov R4, var2 
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Description 


Example 


.mlist 

.mnolist 

Two directives provide you with the ability to control the listing of 
macro and repeatable block expansions in the listing file: 

• The .mlist directive allows macro and .loop/.endloop block 
expansions in the listing file. 

• The .mnolist directive inhibits macro and .loop/.endloop block 
expansions in the listing file. 

By default, all code encountered in macros and .loop/.endloop blocks 
is listed. 

This example shows how to define a macro named str_3. The first time 
the macro is called, the macro expansion is listed (by default). The 
second time the macro is called, the macro expansion is not listed, 
because a .mnolist directive was assembled. The third time the macro 
is called, the macro expansion is again listed because a .mlist directive 
was assembled. 


1 


str_3 

. MACRO 

pml, 

pm2, pm3 

2 



. string 

" :pml 

:", ":pm2 

3 



.ENDM 



4 






5 

0000 


str_3 

"as", 

"I","am" 

1 

0000 

61 

.string 

"as" , 

"I", "am 


0001 

73 





0002 

49 





0003 

61 





0004 

6d 




6 



.mnolist 



7 

0005 


str_3 

"as", 

"I","am" 

8 



.mlist 



9 

000a 


str_3 

"as" , 

"I","am" 

1 

000a 

61 

.string 

"as", 

"I", "am 


000b 

73 





000c 

49 





OOOd 

61 





OOOe 

6d 
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Syntax 

Description 


Exampie 


.newblock 

The .newblock directive undefines any local labels currently defined. A 
local label, by nature, is temporary; the .newblock directive resets local 
labels and terminates their scope. 

A local label is a label in the form $/7, where n is a single decimal digit. 
A local label, like other labels, points to an instruction byte. Unlike 
other labels, local labels cannot be used in expressions; they can be 
used only as the operand in 10-bit jump instructions. Local labels are 
not included in the symbol table. 

After a local label has been defined and (perhaps) used, you should 
use the .newblock directive to reset it. Note that the .text, .data, and 
.sect directives also reset local labels and that local labels that are 
defined within an include file are not valid outside of the include file. 

This example shows how the local label $1 is declared, reset, and then 


declared again. 





1 0000 

4c0d 

Label1: 

mov 

R12, 

R13 

2 0002 

2000 


jnz 

$1 


3 0004 

433d 


mov 

#-l. 

rl3 

4 0006 

9d04 

$1 

cmp 

R13, 

R4 

5 



.newblock 

;undefine $1 

6 0008 

2000 


jne 

$1 


7 000a 

531d 


inc 

R13 


8 000c 

5d0e 

$1 

add 

R13, 

R14 
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Syntax 

Description 


.option option list 

The .option directive selects several options for the assembler output 
listing. The option list is a list of options separated by commas; each 
option selects a listing feature. Valid options include: 

A Turns on all listing (overrides all other directives and options). 

B Limits the listing of .byte directives to one line. 

F Resets the B, M, W, and T options. 

M Turns off macro expansions in the listing. 

T Limits the listing of .string directives to one line. 

W Limits the listing of .word directives to one line. 

X Produces a symbol cross-reference listing. 

Options are not case-sensitive. 


4-55 





Assembler Directives 


MSP430 Family 


Example 


This example shows how to limit the listings of the .byte, .word, and 
.string directives to one line each. 


1 



**************************************** 

2 



* Limit the listing of .byte, .word, * 

3 



* .string directives to 1 line each * 

4 




5 



.option B, W, T 

6 

0000 

bd 

.byte -'C, OBOh, 5 

7 

0004 

15aa 

.word 5546, 78h 

8 

0008 

59 

.string "YES" 

9 



**************************************** 

10 



* Reset the listing options * 

11 



**************************************** 

12 



.option F 

13 

000b 

bd 

.byte -'C, OBOh, 5 


000c 

bO 



OOOd 

05 


14 

OOOe 

15aa 

.word 5546, 78h 


0010 

0078 


15 

0012 

59 

.string "YES" 


0013 

45 



0014 

53 


16 



**************************************** 

17 



* Use The A option to ignore all * 

18 



* other options and directives * 

19 



**************************************** 

20 



.option A 

21 



.nolist 

22 



.option B, W, T 

23 

0015 

bd 

.byte -'C, OBOh, 5 


0016 

bO 



0017 

05 


24 

0018 

15aa 

.word 5546, 78h 


001a 

0078 


25 

001c 

59 

.string "YES" 


OOld 

45 



OOle 

53 


26 



. list 
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Syntax 

Description 


Example 


■page 

The .page directive produces a page eject in the listing file. The .page 
directive is not printed in the source listing, but the line counter is 
incremented. Using the .page directive to divide the source listing into 
logical divisions improves program readability. 

This example shows how the .page directive causes the assembler to 
begin a new page of the source listing. 

Source file: 

.title '■**** Page Directive Example ****" 


.page 

Listing file: 

MSP TSS430 Macro Assembler Prototype Version 1.0 [Mar 22] Wed Aug 18 08:34:18 1993 
Copyright (c) 1993 Texas Instruments Incorporated 

**** Page Directive Example **** PAGE 1 

2 

3 

4 

MSP TSS430 Macro Assembler Prototype Version 1.0 [Mar 22] Wed Aug 18 08:34:18 1993 
Copyright (c) 1993 Texas Instruments Incorporated 

**** Page Directive Example **** PAGE 2 
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Syntax 

Description 


Exampie 


.sect "section name"[,address] 

The .sect directive defines a named section that can be used like the 
default .text and .data sections. The .sect directive begins assembling 
source code into the named section. 

• The section name identifies a section that the assembler 
assembles code into. The name is significant to 8 characters and 
must be enclosed In double quotes. 

• The address is an optional parameter that specifies a 16-bit 
address. It can be used only the first time a .sect directive is 
specified for a particular section. Normally, the SPC is set to 0 the 
first time a named section is assembled; you can use the address 
parameter to assign an initial value to the SPC. This parameter has 
no effect on the final address of the section; it simply makes the 
listing easier to read. 

This example shows how two special-purpose sections, Sym_Defs 
and Vars, are defined, and how code assembles into them. 
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Syntax 

Description 


symbol .set value 
symbol .equ value 

The .set and .equ directives equate a constant value to a symbol. The 
symbol can then be used in place of a value in assembly source. This 
allows you to equate meaningful names with constants and other 
values. The .set and .equ directives are identical and can be used 
interchangeably. 

• The symbol must appear in the label field. 

• The value must be a well-defined expression; that is, all symbols 
in the expression must be previously defined in the current source 
module. 

Undefined external symbols and symbols that are defined later in the 
module cannot be used in the expression. If the expression is 
relocatable, the symbol to which it is assigned is also relocatable. 

The value of the expression appears in the object field of the listing. 
This value is not part of the actual object code and is not written to the 
output file. 
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Example 


This example shows how symbols can be assigned with .set. 


0000 


;* Equate symbol FP to register Rll * 
;* and use it instead of Rll * 
.**•**************■************★***★**** 


Ob 

4b24 


FP 


.set Rll 

MOV @FP, R4 


i^'k-k-k'k'k'k'k'k 




10 



;* expression and use it as an * 

11 



;* immediate operand * 

12 



.*****************•*■*********•******■*■*** 

13 


35 

count .equ 100/2+3 

14 

0002 

40340035 

MOV #count, R4 

15 




16 



.*******************^r***************** 

17 



;* Set symbol symtab to relocatable * 

18 



;* expression * 

19 



.**********■**********■***************** 

20 

0006 

000a 

label .word 10 

21 


' 07 

symtab .set label+1 

22 

0008 

' 0007 

.word symtab 

23 




24 



.**************************:lr********** 

25 



;* Set symbol nsyms to another * 

26 



;* symbol (count) and use it instead * 

27 



;* of count * 

28 



.*******************■****************** 

29 


35 

nsyms .equ count 

30 

000a 

40340035 

MOV #nsyms, R4 
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Syntax 

Description 


Example 


.space size in bytes 

The .space directive reserves size number of bytes in the current 
section and fills them with Os. The section program counter is 
incremented to point to the byte following the reserved space. 

When you use a label with the .space directive, it points to the first byte 
reserved. 


This example shows how the .space directive reserves memory. 


0000 


9 0000 
10 0010 
0012 

11 

12 

13 

14 

15 0000 

16 0000 
0001 
0002 
0003 
0004 

17 

18 

19 

20 
21 

22 0005 

23 006a 

24 006c 


0100 

0200 


2e 

64 

61 

74 

61 


OOOf 

"0005 


Begin assembling into .text 
. text 


Reserve 15 bytes in .text 

'k'k'k-k-k-k-k'k'k'ki^ic'k'k'ki^ic-k'k-k'k'k'kicici^'k 


.space Ofh 
.word lOOh, 200h 


;* Begin assembling into .data 


. data 

.string ".data" 


. ************************ 


;* Reserve 100 bytes in .data; 

;* Res_l points to the first byte 


************ 


Res_l 


.space 100 
.word 15 
.word Res_l 
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Syntax 

Description 


.sslist 

.ssnolist 

Two directives enable you to control substitution symbol expansion in 
the listing file: 

• The .sslist directive allows substitution symbol expansion in the 
listing file. The expanded line appears below the actual source line. 

• The .ssnolist directive inhibits substitution symbol expansion in 
the listing file. 

By default, all substitution symbol expansion in the listing file is 
inhibited. The lines with the pound (#) character denote expanded 
substitution symbols. 
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Example 


This example shows code that by default (.ssnolist directive) inhibits 
the listing of substitution symbol expansion, and it shows the .sslist 
directive assembled, which tells the assembler to list substitution 
symbol code expansion. 



1 

0000 



. bss 

X, 1 


2 

O 

0001 



. bss 

y,i 


4 



ADD2 

.macro 

pml, pm2 


5 




mov 

pml,R4 


6 




mov 

R4, R5 


7 




mov 

pm2, R4 


8 




add 

R5, R4 


9 




mov 

R4, pm2 


10 




. endm 



11 







12 




. asg 

Rll, FP 


13 




. asg 

R13, SSP 


14 







15 

0000 

4b0d 


mov 

FP, SSP 


16 

0002 



add2 

X, y 

1 


0002 

-40140000 


mov 

X, R4 

1 


0006 

4405 


mov 

R4, R5 

1 


0008 

-4014fff7 


mov 

y, R4 

1 


000c 

5504 


add 

R5, R4 

1 

17 

OOOe 

-4480fffl 


mov 

R4, y 


18 




.sslist 



19 







20 

0012 

4b0d 


mov 

FP, SSP 

# 





mov 

Rll, R13 


21 

0014 



add2 

X, y 

1 


0014 

-40140000 


mov 

pml,R4 

# 





mov 

X, R4 

1 


0018 

4405 


mov 

R4 , R5 

1 


001a 

-4014ffe5 


mov 

pm2, R4 

# 





mov 

y, R4 

1 


OOle 

5504 


add 

R5, R4 

1 


0020 

-4480ffdf 


mov 

R4, pm2 

# 





mov 

R4, y 
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Syntax 

[ stagi ] 
[memo] 

[ mem-f ] 

.struct 

element 

element 

[ expr-j ] 
[expr2] 
[expr2] 


[ memn ] 

.tag stag 2 

[,expr2] 


[ me/77/v ] 

[ size ] 

element 

.endstruct 

[expr2] 


label 

■tag 

stag-i 


Description The .struct directive assigns symbolic offsets to the elements of a data 

structure definition. This enables you to group similar data elements 
together and then let the assembler do the element offset calculation. 
This is similar to a C structure or a Pascal record. The .struct directive 
does not allocate any memory; it merely creates a symbolic template 
that can be used repeatedly. 

The .tag directive gives structure characteristics to a label, simplifying 
the symbolic representation and providing the ability to define 
structures that contain other structures, .tag does not allocate memory. 
The structure tag (stag) of a .tag directive must have been previously 
defined. 

[ stag-f ] Is the structure's tag. Its value is associated with the 
beginning of the structure. If no stag is present, this tells the 
assembler to put the structure members in the global symbol 
table with their value being their absolute offset from the top 
of the structure. 

[ expr-f ] Is an expression indicating the beginning offset of the 
structure. Structures default to start at 0. 

[ mem^ ] Is a label for a member of the structure. This label is absolute 
and equates to the present offset from the beginning of the 
structure. 

element Is one of the following descriptors: .string, .byte, .word, 
.float, .double, .tag, and .field. All of these, except .tag, are 
typical directives that initialize memory. Following a .struct 
directive, these directives describe the structure element's 
size. They do not allocate memory. A .tag directive is a 
special case because a stag must be specified (such as 
stag2 in the definition). 

[ expr 2 ] Is an expression for the number of elements described. This 
value defaults to 1. 

[ size ] Is a label for the total size of the structure. 
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Note: 

The Types of Directives That Can Appear in a .struct/.endstruct 


Sequence 




The only 

directives that 

can appear 

in a .struct/.endstruct sequence are element 

descriptors, conditional assembly directives, and the .align and .even directives, which 
align the member offsets on byte resp. word boundaries. Note that empty structures are 

illegal. 







Examples 

1 


0000 

real_rec 

.struct 

/ stag 


2 


0000 

nom 

• byte 

/member1 = 0 


3 


0001 

den 

.byte 

/member2 = 1 


4 

5 

6 


0002 

real_len 

.endstruct 

/real_len = 2 


0000 

-4014ffff 

mov real+real 

_rec.den,R4 /access 


8 

9 

0000 



.bss real,real 

_len /allocate 


10 


0000 

cplx_rec 

.struct 

/ stag 


11 


0000 

real! 

.tag real_rec 

/member1 = 0 


12 


0002 

imagi 

.tag real_rec 

/member2 = 2 


13 


0004 

cplx_len 

.endstruct 

/cplx_len = 4 


14 







15 



complex 

.tag cplx_rec 



16 

0002 



.bss complex,cplx_len /allocate 


17 







18 

0004 

-4014fffe 

mov complex.imagi.nom,R4 


19 

20 

0008 

-9014fff9 

cmp complex.reali.den,R4 


21 


0000 


.struct 

/no stag puts members 


22 





/into global symbol table 


23 


0000 

X 

.byte 

/create 3dim templates 


24 


0001 

y 

.byte 



25 


0002 

z 

.byte 



26 




.endstruct 



27 







28 


0000 

bit_rec 

.struct 

/ stag 


29 


0000 

stream 

.string 64 



30 


0040 

bit7 

.field 7 



31 


0040 

bit2 

.field 2 



32 


0041 

bits 

.field 5 



33 


0042 

x_int 

.byte 



34 


0043 

bit_len 

.endstruct 



35 







36 



bits 

.tag bit_rec 



37 

0006 



.bss bits,bit_ 

len 


38 







39 

000c 

-40140038 

mov bits.bit7,R4 /load field 


40 

0010 

f034007f 

and #7fh,R4 

/mask off garbage 
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Syntax 

Description 


Example 


.text [address] 

The .text directive tells the assembler to begin assembling into the .text 
section, which usually contains executable code. The section program 
counter is set to 0 if nothing has yet been assembled into the .text 
section. If code has already been assembled into the .text section, the 
section program counter is restored to its previous value in the section. 

The address is an optional parameter that specifies a 16-bit address. 
It can be used only the first time a .text directive is specified. Normally, 
the section program counter is set to 0 the first time the .text section is 
assembled; you can use this parameter to assign an initial value to the 
.text section program counter. This parameter has no effect on the final 
address of the section; it simply makes the listing easier to read. 

Note that the assembler assumes that .text is the default section. 
Therefore, at the beginning of an assembly, the assembler assembles 
code into the .text section unless you specify one of the other sections 
directives (.data or .sect). 


This example shows code assembled into the .text and .data sections. 


The .data 

section 

contains integer constants, and 

contains character strings. 

1 



• 'k-k'k'k'k'k'k-k'k'k'k'k-kic'k'k'k-k'k'k'k'k-k'k-k 

2 



;* Begin assembling into ,( 

3 



. ************************* 

4 

0000 


. data 

5 

0000 

05 

.byte 5,6 


0001 

06 


D 

7 



. ************************** 

8 



;* Begin assembling into .1 

9 



. •k'k-kic-k'k'k'k'k'k'k-k'k'kic'k'k'k'k-k-k'k'k'k'k 

10 

7000 


.text 7000h 

11 

7000 

01 

.byte 1 

12 

7001 

02 

•byte 2, 3 


7002 

03 


13 




14 



• 'k'k-k-kic-k-k'k-k-k-k-k'k-k-k-k-k-k'k'k-k-k-k-kii- 

15 



;* Resume assembling into 

16 



. ************************** 

17 

0002 


. data 

18 

0002 

07 

.byte 7,8 


0003 

08 


19 




20 



. ************************** 

21 



;* Resume assembling into 

22 



• •k-k'k'k'k'k'k'k'k'k'k'k'k'kic'k'k-k-k'k'k'k'k'k'k 

23 

7003 


. text 

24 

7003 

04 

.byte 4 
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Syntax .title "string" 

Description The .title directive supplies a title that is printed in the heading on each 

listing page. The source statement itself is not printed, but the line 
counter is incremented. The string is a quote-enclosed title of up to 65 
characters. If you supply more than 65 characters, the assembler 
truncates the string and issues a warning. 

The assembler prints the title on the page that follows the directive and 
on subsequent pages until another .title directive is processed. If you 
want a title on the first page of a listing, the first source statement must 
contain a .title directive. 


Exampie This example shows how to print one title on the first page and a 

different title on succeeding pages. 

Source file: 

.title "** Integer Routines **" 


.title "** Floating Point Routines **" 

. page 

Listing file: 

MSP TSS430 Macro Assembler Prototype Version 1.0 [Mar 22] Wed Aug 18 11:01:02 1993 
Copyright (c) 1993 Texas Instruments Incorporated 


** Integer Routines ** 


PAGE 


1 


2 

3 

4 

MSP TSS430 Macro Assembler Prototype Version 1.0 [Mar 22] Wed Aug 18 11:01:02 1993 
Copyright (c) 1993 Texas Instruments Incorporated 

** Floating Point Routines ** PAGE 2 
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Syntax 

Description 


Example 


symbol .usect "section name", size in bytes 

The .usect directive reserves space for variables in an uninitialized, 
named section. This directive is similar to the .bss directive; both 
simply reserve space for data and have no contents, .usect defines 
additional sections, however, that can be placed anywhere in 
memory, independently of the .bss section. 

• The symbo/points to the first location reserved by this invocation of 
the .usect directive. The symbol corresponds to the name of the 
variable that you're reserving space for. 

• The section name must be enclosed in double quotes; only the first 
8 characters are significant. This parameter names the uninitialized 
section. 

• The size is an expression that defines the number of bytes that are 
reserved in section name. 

• The address is an optional parameter that specifies a 16-bit 
address. It can be used only the first time a .usect directive is 
specified for a particular section. Normally, the SPC is set to 0 the 
first time a named section is assembled; you can use the address 
parameter to assign an initial value to the SPC. This parameter has 
no effect on the final address of the section. 

Other sections directives (.text, .data, and .sect) end the current 
section and tell the assembler to begin assembling into another 
section. The .usect, .bss, .regpair, and .reg directives, however, do not 
affect the current section. The assembler assembles the .usect, .bss, 
.regpair, and .reg directives and then resumes assembling into the 
current section. 

You can repeat the .usect directive to define more than one variable in 
the specified section. Variables that can be located contiguously in 
memory can be defined in the same section by using multiple .usect 
directives with the same section name. 

This example shows how to use the .usect directive to define two 
uninitialized, named sections, varl and var2. The symbol ptr points to 
the first byte reserved in the varl section. The symbol array points to 
the first byte in a block of 100 bytes reserved in varl, and dflag points 
to the first byte in a block of 50 bytes in varl. The symbol vec points to 
the first byte reserved in the var2 section. 
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Example 4.8: The .usect Directive 
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Syntax .word value^ value 

Description The .word directive places one or more 16-bit values into consecutive 

two-byte pairs in the current section. 

The values can be either absolute or relocatable expressions. If an 
expression is relocatable, the assembler generates a relocation entry 
that refers to the appropriate symbol; the linker can then correctly 
patch (relocate) the reference. This allows you to initialize memory with 
pointers to variables or labels. 

You can use as many values as fit on a single line. If you use a label, it 
points to the first word that is initialized. 

Note that when you use .word in a .struct/.endstruct sequence, it 
defines a member's size; it does not initialize memory. 

Example This example shows how to use the .word directive to initialize words. 

The symbol WordX points to the first word that is reserved. 


1 0000 

0c80 Wordx: 

.word 

3200, l+'B', 

-Oafh, 'X' 

0002 

0043 




0004 

ff51 




0006 

0058 
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5 Instruction Set Summary 

This chapter summarizes the MSP430 family instruction set. 
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5.1 Symbols and Abbreviations 

The following table lists the instruction set symbols and abbreviations used throughout the 
rest of this chapter. 


Symbol 

Definition 

Symbol 

Definition 

src 

The source operand defined by 

As and S-reg 

dst 

The destination operand defined 
by Ad and D-reg 

As 

The bits representing the 
addressing mode used for the 
source 

Ad 

The bit representing the 
addressing mode used for the 
destination 

S-reg 

The used Working Register for 
the source src 

D-reg 

The used Working Register for 
the destination dst 

RO or PC 

Register 0 or Program Counter 

R1 orSP 

Register 1 or Stack Pointer 

R2 or 

Register 2 or Status 

R3 or 

Register 3 or Constant 

SR/CG1 

Register/Constant Generator 1 

CG2 

Generator 2 

R4 to 

R15 

Working Register, 
general purpose 

Rn 

Working Register with n=4-15, 
general purpose 

# 

Immediate Data 

@ 

Register indirect addressing 

& 

Absolute address 

“> 

Data transfer direction 

label 

16-bit label 

TOS 

Top of Stack 

C 

Carry Bit 

N 

Negative Bit 

V 

Overflow Bit 

Z 

Zero Bit 

.B 

The suffix .B at the instruction 
memonic will result in a byte 
operation 

.w 

The suffix .W or no suffix at the 
instruction memonic will result in 
a word operation 

MSB 

Most significant Bit 

LSB 

Least significant Bit 


Table 5.1: Symbols and Abbreviations used in the Instruction Set Summary 
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5.2 Addressing Modes 


All seven addressing modes for the source operand and all four addressing modes for the 
destination operand can address the complete address space. The bit numbers show the 
contents of the As resp. Ad mode bits. 


As 

Ad 

Addressing Mode 

Syntax 

Description 

00 

0 

Register Mode 

Rn 

Register contents are operand 

01 

1 

Indexed Mode 

X(Rn) 

(Rn + X) points to the operand. 

X is stored in the next word 

01 

1 

Symbolic Mode 

ADDR 

(PC + X) points to the operand. 

X is stored in the next word. Indexed 

Mode X(PC) is used 

01 

1 

Absolute Mode 

&ADDR 

The word following the instruction 
contains the absolute address. 

10 

- 

Indirect Register 
Mode 

@Rn 

Rn is used as a pointer to the operand 

11 

- 

Indirect 

Autoincrement 

@Rn+ 

Rn is used as a pointer to the operand. 

Rn is incremented afterwards 

11 


Immediate Mode 

#N 

The word following the instruction 
contains the immediate constant N. 
Indirect Autoincrement Mode @PC+ is 
used 


Table 5.2: Addressing Modes 


Note: Addressing Modes 

The addressing modes using the PC as the working register use the normal effects of the 
addressing modes. The special addressing modes are caused by the pointing of the PC to 
the ROM word following the currently executed instruction. 
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5.3 Instruction Set Summary 


Status Bits 






V 

N 

z 

c 

* 

ADC(.B) 

dst 

dst + C dst 

X 

X 

X 

X 


ADD(.B) 

src.dst 

src + dst ^ dst 

X 

X 

X 

X 


ADDC(.B) 

src.dst 

src + dst + C -> dst 

X 

X 

X 

X 


AND(.B) 

src,dst 

src .and. dst -> dst 

0 

X 

X 

X 


BIC(.B) 

src,dst 

.not.src .and. dst ^ dst 

- 

- 

- 

- 


BIS(.B) 

src,dst 

src .or. dst ^ dst 

- 

- 

- 

- 


BIT(.B) 

src.dst 

src .and. dst 

0 

X 

X 

X 

* 

BR 

dst 

Branch to. 

- 

- 

- 

- 


CALL 

dst 

PC+2 stack, dst ^ PC 

- 

- 

- 

- 

* 

CLR(.B) 

dst 

Clear destination 

- 

- 

- 

- 

* 

CLRC 


Clear carry bit 

- 

- 

- 

0 

* 

CLRN 


Clear negative bit 

- 

0 

- 

- 


CLRZ 


Clear zero bit 

- 

- 

0 

- 


CMP(.B) 

src.dst 

dst - src 

X 

X 

X 

X 

* 

DADC(.B) 

dst 

dst + C -> dst (decimal) 

X 

X 

X 

X 


DADD(.B) 

src.dst 

src + dst + C ^ dst (decimal) 

X 

X 

X 

X 

* 

DEC(.B) 

dst 

dst -1 ^ dst 

X 

X 

X 

X 

* 

DECD(.B) 

dst 

dst - 2 ^ dst 

X 

X 

X 

X 

* 

DINT 


Disable interrupt 

- 

- 

- 

- 

•k 

EINT 


Enable interrupt 

- 

- 

- 

- 

k 

INC(.B) 

dst 

Increment destination, dst +1 -> dst 

X 

X 

X 

X 

k 

INCD(.B) 

dst 

Double-Increment destination. dst+2^dst 

X 

X 

X 

X 

k 

INV(.B) 

dst 

Invert destination 

X 

X 

X 

X 


JC/JHS 

Label 

Jump to Label if Carry-bit is set 

- 

- 

- 

- 


JEQ/JZ 

Label 

Jump to Label if Zero-bit is set 

- 

- 

- 

- 


JGE 

Label 

Jump to Label if (N .XOR. V) = 0 

- 

- 

- 

- 


JL 

Label 

Jump to Label if (N .XOR. V) = 1 

- 

- 

- 

- 


JMP 

Label 

Jump to Label unconditionally 

- 

- 

- 

- 


JN 

Label 

Jump to Label if Negative-bit is set 

- 

- 

- 

- 


Legend: 0 Status bit always cleared 1 Status bit always set 

X Status bit cleared or set on results - Status bit not affected 
* Emulated Instructions 

Table 5.3: MPS430 Family Instruction Set Summary 
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Status Bits 






V 

N 

z 

c 


JNC/JLO 

Label 

Jump to Label If Carry-bit is reset 

- 

- 

- 

- 


JNE/JNZ 

Label 

Jump to Label if Zero-bit is reset 

- 

- 

- 

- 


MOV(.B) 

src,dst 

src ^ dst 

- 

- 

- 

- 

* 

NOP 


No operation 

- 

- 

- 

- 

* 

POP(.B) 

dst 

Item from stack, SP-i-2 ^ SP 

- 

- 

- 

- 


PUSH(.B) 

src 

SP - 2 SP, src ^ @SP 

- 

- 

- 

- 


RETI 


Return from interrupt 

TOS ^ SR, SP + 2 ^ SP 

TOS ^ PC, SP + 2 ^ SZP 

X 

X 

X 

X 


RET 


Return from subroutine 

TOS ^ PC, SP + 2 ^ SP 

- 

- 

- 

- 

* 

RLA(.B) 

dst 

Rotate left arithmetically 

X 

X 

X 

X 

* 

RLC(.B) 

dst 

Rotate left through carry 

X 

X 

X 

X 


RRA(.B) 

dst 

MSB ^ MSB ....LSB->C 

0 

X 

X 

X 


RRC(.B) 

dst 

C-^MSB .LSB^C 

X 

X 

X 

X 


SBC(.B) 

dst 

Subtract carry from destination 

X 

X 

X 

X 

* 

SETC 


Set carry bit 

- 

- 

- 

1 

* 

SETN 


Set negative bit 

- 

1 

- 

- 

* 

SETZ 


Set zero bit 

- 

- 

1 

- 


SUB(.B) 

src, dst 

dst + .not.src + 1 ^ dst 

X 

X 

X 

X 


SUBC(.B) 

src,dst 

dst + .not.src + C ^ dst 

X 

X 

X 

X 


SWPB 

dst 

swap bytes 

- 

- 

- 

- 


SXT 

dst 

Bit7 ^ Bits.Bit15 

0 

X 

X 

X 

* 

TST(.B) 

dst 

Test destination 

X 

X 

X 

X 


XOR(.B) 

src,dst 

src .xor. dst dst 

X 

X 

X 

X 


Legend: 0 The Status Bit is cleared 1 The Status Bit is set 

X The Status Bit is affected - The Status Bit is not affected 

* Emulated Instructions 


Table 5.3: MPS430 Family Instruction Set Summary (Concluded) 


Note: Emulated Instructions 

All marked instructions (*) are emulated instructions. The emulated instructions use core 
instructions combined with the architecture and implementation of the CPU for higher code 
efficiency and faster execution. 
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5.4 Clock cycles, Length of Instruction 

The operating speed of the CPU is independent from individual instructions. It depends on 
the instruction format and the addressing modes. The number of clock cycles refer to the 
internal oscillator frequency. 


5.4.1 Format I Instructions 


Address Mode 

#of cycles 

Length of 
instruction 

Example 

As 

Ad 

00, Rn 

0, Rm 

1 

1 

MOV R5,R8 


0,PC 

2 

1 

BR R9 

00, Rn 

1, x(Rm) 

4 

2 

ADD R5,3(R6) 


1, EDE 


2 

XOR R8,EDE 


1, &EDE 


2 

MOV R5,&EDE 

01, x(Rn) 

0, Rm 

3 

2 

MOV 2(R5),R7 

01, EDE 



2 

AND EDE,R6 

01, &EDE 




MOV &EDE,R8 

01, x(Rn) 

1, x(Rm) 

6 

3 

ADD 3(R4),6(R9) 

01, EDE 

1,TONI 


3 

CMP EDE,TONI 

01, &EDE 

1,&TONI 


3 

MOV 2(R5),&TONI 





ADD EDE,&TONI 

10, @Rn 

0, Rm 

2 

1 

AND @R4,R5 

10, @Rn 

1,x(Rm) 

5 

2 

XOR @R5,8(R6) 


1, EDE 


2 

MOV @R5,EDE 


1, &EDE 


2 

XOR @R5,&EDE 

11, @Rn+ 

0, Rm 

2 

1 

ADD @R5+,R6 


0, PC 

3 

1 

BR @R9+ 

11, #N 

0, Rm 

2 

2 

MOV #20,R9 


0, PC 

2 

2 

BR #2AEh 

11, @Rn+ 

1,x(Rm) 

5 

2 

MOV @R9+,2(R4) 

11, #N 

1, EDE 


3 

ADD #33,EDE 

11, @Rn+ 

1,&EDE 


2 

MOV @R9+,&EDE 

11, #N 


_1 

3 

ADD #33,&EDE 


Table 5.4: Format I Instructions 


Note: Cycle Time of the DADD Instruction 

The DADD instruction needs 1 extra cycle. 
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5.4.2 Format II Instructions 


Address Mode 

#of cycles 

Length of 

Example 

A(s/d) 

RRC 

PUSH/ 

instruction 


RRA 

SWPB 

SXT 

CALL 

[words] 



00, Rn 

1 

3/4 

1 

SWPB R5 

01, x(Rn) 

4 

5 

2 

CALL 2(R7) 

01, EDE 

4 

5 

2 

PUSH EDE 

10, @Rn 

3 

4 

1 

RRC @R9 

11,@Rn+ see Note 

3 

4/5 

1 

SWPB @R10+ 

11, #N 

3 

4/5 

2 

CALL #81 h 


Table 5.5: Format II Instructions 


Note: Immediate mode in destination field 

Instructions should not use immediate mode in the destination field. This would result in 
unpredictable program operation. 


5.4.3 Format III Instructions 

Jxx - instructions need all the same #-of-cycles independent of a successful! Jump or not. 

Clock Cycle: 2 Cycle. 

Length of Instruction: 1 word. 


5.4.4 Miscellanous Instructions or Operators 

RETI Clock Cycle: 5 Cycle. 

Length of instruction: 1 word. 
Interrupt Clock Cycle: 6 Cycle. 
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6 Macro Language 

The assembler supports a macro language that enables you to create your own “instruc¬ 
tions." This is especially useful when a program executes a particular task several times. The 
macro language enables you to: 

• Define your own macros and redefine existing macros. 

• Simplify long or complicated assembly code. 

• Access macro libraries created with the archiver. 

• Define conditional and repeatable blocks within a macro. 

• Manipulate strings within a macro. 

• Control expansion listing. 
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6.1 Using Macros 

Programs often contain routines that are executed several times. Instead of repeating the 
source statements for a routine, you can define the routine as a macro, then call the macro in 
the places where you would normally repeat the routine. This simplifies and shortens your 
source program. 

If you want to call a macro several times, but with different data each time, you can assign 
parameters to a macro. This enables you to pass different information to the macro each 
time you call it. The macro language supports a special symbol called a substitution 
symbol, which is used for macro parameters. In this chapter, we use the terms macro 
parameters and substitution symbols interchangeably. 

Using a macro is a three-step process: 

Stepi: Define the macro. You must define macros before you can use them in your 
program. There are two methods for defining macros; 

• Macros can be defined at the beginning of a source file or in an .include/.copy 
file. 

• Macros can also be defined in a macro library. A macro library is a collection of 
files in archive format, created by the archiver. Each member of the archive file 
(macro library) may contain one macro definition corresponding to the member 
name. You can access a macro library by using the .mlib directive. 

Step 2: Call the macro. After you have defined a macro, you can call it by using the macro 
name as an opcode in the source program. This is referred to as a macro call. 

Step 3: Expand the macro. The assembler expands your macros when the source program 
calls them. During expansion, the assembler passes arguments by variable to the 
macro parameters, replaces the macro call statement with the macro definition, then 
assembles the source code. By default, the macro expansions are printed in the 
listing file. You can turn off expansion listing by using the .mnolist directive. 

When the assembler encounters a macro definition, it places the macro name in the opcode 
table. This redefines any previously defined macro, library entry, directive, or instruction 
mnemonic that has the same name as the encountered macro. This allows you to expand 
the functions of directives and instructions, as well as add new instructions. 
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6.2 Defining Macros 

You can define a macro anywhere in your program, but you must define the macro before 
you can use it. Macros can be defined at the beginning of a source file or in an .include/.copy 
file; they can also be defined in a macro library. 

The contents of a macro definition must be contained in the same file. Macro definitions can 
be nested, and they can call other macros. 

A macro definition is a series of source statements in the following format: 
macname .macro [parameter-f] [,parameter 2 ]...[,parameter 
model statements or macro directives 

[.mexit] 

.endm 

macname names the macro. You must place the name in the source statement's 

label field. Only the first 32 characters of a macro name are significant. 
The assembler places the macro name in the internal opcode table, 
replacing any instruction or previous macro definition with the same 
name. 

is a directive that identifies the source statement as the first line of a 
macro definition. You must place .macro in the opcode field. 

are optional substitution symbols that appear as operands for the 
.macro directive. 

model statements are instructions or assembler directives that are executed each time 
the macro is called. 

macro directives are used to control macro expansion. 

[.mexit] functions as a “goto .endm". The .mexit directive is useful when error 

testing confirms that macro expansion will fail. 

.endm terminates the macro definition. 


.macro 

[parameters] 
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Macro definition: The following code defines a macro, add3, with 3 parameters: 

1 

2 

3 

4 



;* add3 argl, arg2, arg3 
;* arg3 = argl + arg2 + arg3 



add3 .macro argl, arg2, arg3 

6 



mov argl, R4 

7 



mov R4, R5 

8 



mov arg2, R4 

9 



add R4, R5 

10 



mov arg3, R4 

11 



add R5, R4 

12 



mov R4, arg3 

13 



. endm 

Macro Call: The following code calls the add3 macro with 3 arguments 

14 




15 

0000 


add3 X, y ,z 

Macro Expansion: The following code shows the substitution of the macro definition for the 
macro call. The assembler passes the arguments (supplied in the macro call) by variable 

to the parameters (substitution symbols). 


1 

1 

0000 

-40140000 

mov X, R4 

1 

0004 

4405 

mov R4, R5 

1 

0006 

-4014fff9 

mov Y, R4 

1 

000a 

5405 

add R4, R5 

1 

000c 

-4014fff4 

mov z, R4 

1 

0010 

5504 

add R5, R4 

1 

0012 

-4480ffee 

mov R4, z 

16 




17 




18 



;* Reserve space for vars 

19 

0000 


.bss x,l 

20 

0001 


.bss y,1 

21 

0002 


.bss z,l 


Example 6.1: Macro Definition, Call, and Expansion 


If you want to include comments with your macro definition but don't want those comments 
to appear in the macro expansion, precede your comments with an exclamation point. If you 
do want your comments to appear in the macro expansion, use an asterisk or semicolon in 
place of the exclamation point. 
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6.3 Macro Parameters/Substitution Symbols 

If you want to call a macro several times, but with different data each time, you can assign 
parameters to the macro. The macro language supports a special symbol, called a 
substitution symbol, which is used for macro parameters. 

Substitution Symbols- 

Macro parameters are substitution symbols. Substitution symbols are symbols that represent 
a character string. Besides being used as macro parameters, these symbols can also be 
used outside of macros to equate a character string to a symbol name. 

Valid substitution symbols may be 32 characters long and must begin with a letter. The 
remainder of the symbol can be a combination of alphanumeric characters, underscores, and 
dollar signs. 

Substitution symbols used as macro parameters are local to the macro they are defined in. 
You can define up to 32 local substitution symbols (including substitution symbols defined 
with the .var directive) per macro. 

During macro expansion, the assembler passes arguments by variable to the macro 
parameters. The character-string equivalent of each argument is assigned to the 
corresponding parameter. Parameters without corresponding arguments are set to the null 
string. If the number of arguments exceeds the number of parameters, the last parameter is 
assigned the character-string equivalent of all remaining arguments. 

If you pass a list of arguments to one parameter, or if you pass a comma or semicolon to a 
parameter, you must surround the arguments with quotation marks. 

At assembly time, the assembler first replaces the substitution symbol with its corresponding 
character string, then translates the source code into object code. 
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Macro Definition 



Farms .macro 

a,b, c 


; a = 

: a: 


; b = 

:b: 


; c = 

: c : 


, endm 



Calling the Macro, 

Farms 


Farms 

100,label 

Farms 100,label,x,y 

; a = 

100 

; a = 100 

; b = 

label 

; b = label 

; c = 

II II 

; c = x,y 

Farms 

100,X 

Farms "100,200,300",x,y 

; a = 

100 

; a = 100,200,300 

; b =: 

II II 

; b = X 

; c = 

X 

; c = y 

Farms 

"""string""",x,y 


; a = 

"string" 


; b = 

X 


; c = 

y 



Example 6.2: Calling a Macro With Varying Numbers of Arguments 


Directives That Define Substitution Symbols- 

You can manipulate substitution symbols with the .asg and .eval directives. 

• The .asg directive assigns a character string to a substitution symbol. 

The syntax of the .asg directive is: 

.asg [“] character string ["], substitution symbol 

The quotation marks are optional. If there are no quotation marks, the assembler reads 
characters up to the first comma and removes leading and trailing blanks. In either case, 
a character string is read and assigned to the substitution symbol. 

The example shows character strings being assigned to substitution symbols. 


. asg 

R13,FF 

; frame pointer 

. asg 

@ , Ind 

; indirect addressing 

. asg 

"""string""",strng 

; string 

• asg 

"a,b,c",parms 

; parameters 

mov 

Ind(FF),R4 

; mov @ (Rl3 ) , R4 


Example 6.3: Using the .asg Directive 
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• The .eval directive performs arithmetic on numeric substitution symbols. 

The syntax of the .eval directive is: 

.eval well-defined expression, substitution symbol 

The .eval directive evaluates the expression and assigns the string value of the result to 
the substitution symbol. If the expression is not well defined, the assembler generates an 
error and assigns the null string to the symbol. 

The example shows arithmetic being performed on substitution symbols. 


.asg 1, counter 

•loop 100 

.word counter 

.eval counter+1, counter 

.endloop 


Example 6.4: Using the .eval Directive 


In the example, the .asg directive could be replaced with the .eval directive (.eval 1, counter) 
without changing the output. In simple cases like this, you can use .eval and .asg 
interchangeably. If you want to calculate a value from an expression, however, you must use 
the .eval directive. 

The .asg directive only assigns a character string to a substitution symbol, while the .eval 
directive evaluates an expression and then assigns the character string equivalent to a 
substitution symbol. 


Built-In Substitution Symbol Functions - 

The following built-in substitution symbol functions enable you to make decisions based on 
the string value of substitution symbols. These functions always return a value, and they can 
be used in expressions. Built-in substitution symbol functions are especially useful in 
conditional assembly expressions. Parameters to these functions are substitution symbols or 
character-string constants. 

In the following function definitions, a and b are parameters that represent substitution 
symbols or character string constants. The term string, used below, refers to the string value 
of the parameter. 
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Function 

Return Value 

$symlen(aj 

length of string a 

$symcmp(^a,bj 

<0ifa<b 0ifa=jb >0ifa>b 

$f\rsXc}n(a,ch) 

index of the first occurrence of character constant ch in string a 

$\astch(a,ch) 

index of the last occurrence of character constant ch in string a 

$\s6eie6(a) 

1 if string a is defined in the symbol table 

0 if string a is not defined in the symbol table 

$ismemberfa,bj 

top member of list b is assigned to string a 

0 if b is a null string 

$isconsfaj 

1 if string a is a binary constant 

2 if string a is an octal constant 

3 if string a is a hexadecimal constant 

4 if string a is a character constant 

5 if string a is a decimal constant 

$isnamefa) 

1 if string a is a valid symbol name 

0 if string a is not a valid symbol name 

$isregf^a; 

1 if string a is a valid predefined register name 

0 if string a is not a valid predefined register name 


. asg 

Label, x 

; X = label 

.if 

($SYmcmp (x,"Label") = 0) 

; evaluates to true 

cmp 

x,R4 


.endif 



. asg 

"L1,L2,L3", list 

; list = L1,L2,L3 

.if 

($ismember(x, list)) 

; X = LI list rr L2,L3 

cmp 

x,R4 


.endif 




Example 6,5: Using Built-In Substitution Symbol Functions 
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Recursive Substitution Symbols - 

When the assembler encounters a substitution symbol, it attempts to substitute the 
corresponding character string. If that string is also a substitution symbol, the assembler 
performs substitution again. The assembler continues doing this until it encounters a token 
that is not a substitution symbol or until it encounters a substitution symbol that it has already 
encountered during this evaluation. 

In the example, the y is substituted for x; z is substituted for y; and x is substituted for z. The 
assembler recognizes this as infinite recursion and ceases substitution. 


. asg 

"x' 

' / Z 

; declare 

z 

and 

assign 

z = 

"X" 

. asg 

" z ' 

' /Y 

; declare 

y 

and 

assign 

y = 

" z" 

. asg 

"y" ,x 

; declare 

X 

and 

assign 

X = 

"y" 

cmp 

X, 

R4 







cmp 

X, 

R4 

; recursive 

expansion 




Example 6.6: Recursive Substitution 

Forcing Substitutions- 

In some cases, substitution symbols are not recognizable to the assembler. The forced 
substitution operator, which is a set of colons, enables you to force the substitution of a 
symbol's character string. Simply surround a symbol with colons to force the substitution. Do 
not include any spaces between the colons and the symbol. 

The syntax for the forced substitution operator is: 

-.symbol: 

The assembler expands substitution symbols surrounded by colons before it expands any 
other substitution symbols. 

You can use the forced substitution operator only inside of macros, and you cannot nest a 
forced substitution operator within another forced substitution operator. 
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force 

.macro 

X 


* 

. asg 
.loop 8 

0, 

X 

; loop/.endloop are discussed 
in Section 4.0 

AUX: X : 

. * 

. equ X 


; The X in AUXx would not be 
recognizable as a substituion 
symbol by the assembler 


.eval x+1, 

.endloop 
. endm 

X 


force 

;macro call 

This would generate the following source code: 


AUXO 

. equ 

0 


AUXl 

. equ 

1 


AUx7 

. equ 

7 


Example 6.7: Using the Forced Substitution Operator 


Accessing Individual Characters of Subscripted Substitution Symbols - 

In a macro, you can access the individual characters (substrings) of a substitution symbol 
with subscripted substitution symbols. You must use the forced substitution operator for 
clarity. 

You can access substrings in two ways; 

• : symbol ( well-defined expression): 

This method of subscripting evaluates to a character string with one character. 

• : symbol ( well-defined expression f, well-defined expression2 ): 

In this method, expression-] represents the substring's starting position, and expression2 
represents the substring's length. You can specify exactly where to begin subscripting 
and the exact length of the resulting character string. The index of substring characters 
begins with 1, not 0. 

The next two examples show built-in substitution symbol functions used with subscripted 
substitution symbols. 
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In the first example, subscripted substitution symbols redefine the pop instruction so that it 
handles indirect addressing. 


popx 

macro 

X 


. var 

tmp,len 


. asg 

:X(1):,tmp 


.if 

$ symcmp(tmp,"@) = 0 


. eval 

$symlen(x),len 


. asg 

:X(2,len):,tmp 


.if 

$isreg(tmp) 1 


pop 
. else 

0(tmp) 


. emsg 
.endif 
. else 

"Bad Register Name" 


. emsg 
.endif 
. endm 

"Bad Operand" 


popx 

@R4 ; macro call 


Example 6.8: Using Subscripted Substitution Symbols to Redefine an Instruction 


In the second example, the subscripted substitution symbol is used to find a substring strg1 
beginning at position start in the string strg2. The position of the substring strg1 is assigned 
to the substitution symbol pos. 


substr .macro 

start,strgl,strg2,pos 

. var 

lenl,len2,i,tmp 

.if 

$symlen(start) = 0 

. eval 

1,start 

.endif 


. eval 

0, pos 

. eval 

start, i 

. eval 

$symlen(strgl),lenl 

. eval 

$symlen(strg2),len2 

. loop 


.break 

i = (len2-lenl+l) 

. asg 

":strg2(i,lenl):",tmp 

. if 

$symcmp(strgl,tmp) = 0 

. eval 

i, pos 

.break 


. else 


. eval 

i + 1, i 

.endif 


.endloop 


. endm 


. asg 

0, pos 

. asg 

"arl ar2 ar3 ar4",regs 

substr 

1,"ar2",regs,pos 

.word 

pos 

Example 6.9: Using Subscripted Substitution Symbols to Find Substrings 
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Substitution Symbols as Local Variables In Macros - 

If you want to use substitution symbols as local variables within a macro, you can use the 
.var directive to define up to 32 local macro substitution symbols (including parameters) per 
macro. The .var directive creates temporary substitution symbols with the initial value of the 
null string. These symbols are not passed in as parameters, and, after expansion, these 
symbols are lost. 

.var sym y [,sym 2 ]... [,symp] 

The .var directive is used in the last two examples. 


6-14 




MSP430 Family 


Macro Language 


6.4 Macro Libraries 

One of the ways you can define macros is in a macro library. A macro library is a collection 
of files that contain macro definitions. You must use the archiver to collect these files, or 
members, into a single file (called an archive). Each member of a macro library contains one 
macro definition. The files in a macro library must be unassembled source files. The macro 
name and the member name must be the same, and the macro filename's extension must be 
.asm. For example: 


Macro Name Filename in Macro Library 

simple simple.asm 

add3 addB.asm 

You can access the macro library by using the .mlib assembler directive. 

.mlib macro library filename 

When the assembler encounters an .mlib directive, it opens the library and creates a table of 
its contents. The assembler enters the names of the individual members within the library 
into the opcode tables as library entries; this redefines any existing opcodes or macros that 
have the same name. If one of these macros is called, the assembler extracts the entry from 
the library and loads it into the macro table. The assembler expands the library entry in the 
same manner as other macros. You can control the listing of library entry expansions with 
the .mlist directive. Only macros that are actually called from the library are extracted, and 
they are extracted only once. 

You can create a macro library with the archiver by simply including the desired files in an 
archive. A macro library is no different from any other archive, except that the assembler 
expects the macro library to contain macro definitions. The assembler expects only macro 
definitions in a macro library; putting object code or miscellaneous source files into the library 
may produce undesirable results. 
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6.5 Using Conditional Assembly in Macros 

The conditional assembly directives are .if/.elseif/.else/.endif and .loop/.break/.endloop. 
They can be nested within each other up to 32 levels deep. The format of a conditional block 
is: 

.if well-defined expression 

code block to execute when the .if expression is true (nonzero) 

[.elseif well-defined expression] 

code block to execute when the .elseif expression is true (nonzero) 

[.else] 

code block to execute when the .elseif expression is false (zero) 

.endif 

The .elseif and .else directives are optional, and they can be used more than once within a 
conditional assembly code block. When they are omitted, and when the .if expression is false 
(zero), the assembler continues to the code following the .endif directive. 

The .loop/.break/.endloop directives enable you to assemble a code block repeatedly. The 
format of a repeatable block is: 

.loop [well-defined expression] 

code block to repeatedly assemble 
[.break [well-defined expression]] 

continue to repeatedly assemble when the .break expression is false (zero) 

.endloop 

code block to execute when the .break expression is true (nonzero) or when the 
.break expression is omitted and the loop count equals expression. 

The .loop directive's optional expression evaluates to the loop count. If the expression is 
omitted, the loop count defaults to 1024, unless the assembler encounters a .break directive. 

The .break directive and its expression are optional. If the expression evaluates to false, the 
loop continues. The assembler breaks the loop when the .break expression evaluates to true 
or when the .break expression is omitted and the loop count equals expression. When the 
loop is broken, the assembler continues with the code after the .endloop directive. 

The next three examples show the .loop/.break/.endloop directives, properly nested con¬ 
ditional assembly directives, and built-in substitution symbol functions used in a conditional 
assembly code block. 
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6.6 Using Labels in Macros 

All labels in an assembly language program must be unique. This includes labels in macros. 
If a macro is expanded more than once, its labels are defined more than once. Defining a 
label more than once is illegal. The macro language provides a method of defining labels in 
macros so that the labels are unique. Simply follow the label with a question mark, and the 
assembler will replace the question mark with a period followed by a unique number. When 
the macro is expanded, you will not see the unique number in the listing file. Your label will 
appear with the question mark as it did in the macro definition. The syntax for a unique label 
is: 

label? 
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1 



min 

.macro x,^ 



2 




mov X, R4 



3 




cmp y, r4 



4 




jl ml? 



5 




mov y, R4 



6 



ml? 




7 




, endm 



8 







9 







10 







11 

0000 



.bss varl 



12 

0001 



.bss var2 



13 

0002 



.bss var3 



14 







15 

0000 



min varl, 

var2 

1 


0000 

-40140000 


mov varl. 

R4 

1 


0004 

-9014fffb 


cmp var2, 

r4 

1 


0008 

'3802 


j 1 ml ? 


1 


000a 

-4014fff5 


mov var2, 

R4 

1 

16 

OOOe 


ml? 




17 

OOOe 



min var2, 

var3 

1 


OOOe 

-4014fffl 


mov var2, 

R4 

1 


0012 

-9014ffee 


cmp var3, 

r4 

1 


0016 

'3802 


j 1 ml? 


1 


0018 

-4014ffe8 


mov var3, 

R4 

1 

18 

001c 


ml? 




LABEL 

VALUE 


BEEN 

REF 


ml .1 

OOOe 

. 

15 

15 


ml .2 

001c 

' 

17 

17 


varl 

0000 

- 

11 

15 


var2 

0001 

- 

12 

15 

15 

var3 

0002 

- 

13 

17 

17 


Example 6.12: Unique Labels in a Macro 


The maximum label length is shortened to allow for the unique suffix. For example, if the 
macro is expanded fewer than 10 times, the maximum label length is 30 characters. If the 
macro is expanded from 10 to 999 times, the maximum label length is 29. The label with its 
unique suffix is shown in the cross-listing file. 
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6.7 Producing Messages in Macros 

The macro language supports three directives that enable you to define your own assembly¬ 
time error and warning messages. These directives are especially useful when you want to 
create messages specific to your needs. The last line of the listing file shows the error and 
warning counts. These counts alert you to problems in your code and are especially useful 
during debugging. 

.emsg sends error messages to the listing file. The .emsg directive generates 

errors in the same way the assembler does, incrementing the error count 
and preventing the assembler from producing an object file. 

.wmsg sends warning messages to the listing file. The .wmsg directive functions in 

the same manner as the .emsg directive but increments the warning count 
and does not prevent the generation of an object file. 

.mmsg sends warnings or assembly-time messages to the listing file. The .mmsg 

directive functions in the same manner as the .emsg directive but does not 
set the error count or prevent the generation of an object file. 

Macro comments are comments that appear in the definition of the macro but do not show 
up in the expansion of the macro. An exclamation point in column 1 identifies a macro 
comment. If you want your comments to appear in the macro expansion, precede your 
comment with an asterisk or semicolon. 

The example shows user messages in macros and macro comments that will not appear in 
the macro expansion. 


TEST .MACRO x,y 


This macro checks for the correct number of parameters. 

The macro generates an error message if x an y are not present. 


.if 

. emsg 
.mexit 
. else 


($symlen(x) == 0|$symlen(y) ==0)) ; Test for 

; proper input 

"ERROR - missing parameter in call to TEST" 


. endif 
.if 


.endif 
. endm 

1 error, no warnings 


Example 6.13: Producing Messages in a Macro 
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6.8 Formatting the Output Listing 

Macros, substitution symbols, and conditional assembly directives may hide information. You 
may need to see this hidden information, so the macro language supports an expanded 
listing capability. 

By default, the assembler shows macro expansions and false conditional blocks in the list 
output file. You may want to turn this listing off or on within your listing file. The assembler 
provides three sets of directives that enable you to control the listing of this information. 

• Macro and Loop Expansion Listing 

.mlist expands macros and .loop/.endloop blocks. The.mlist directive prints to the 

listing all code encountered in those blocks. By default, the assembler 
behaves as if you had used .mlist 

.mnolist suppresses the listing expansion of macros and .loop/.endloop blocks. 

• False Conditional Block Listing 

.fclist causes the assembler to print to the listing file all false conditional blocks 

that do not generate code. Conditional blocks appear in the listing exactly 
as they appear in the source code. By default, the assembler behaves as if 
you had used .fclist 

.fcnolist suppresses the listing of false conditional blocks. Only the code in 

conditional blocks that actually assembles appears in the listing. The .if, 
.elsif, .else, and .endif directives do not appear in the listing. 

• Substitution Symbol Expansion Listing 

.sslist expands substitution symbols in the listing. This is useful for debugging the 

expansion of substitution symbols. The expanded line appears below the 
actual source line. 

.ssnolist turns off substitution symbol expansion in the listing. By default, the 

assembler behaves as if you had used .ssnolist 
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6.9 Using Recursive and Nested Macros 

The macro language supports recursive and nested macro calls. This means that you can 
call other macros from inside a macro definition. When you use nested macros, you can call 
different macros from your macro definition. You can nest macros up to 32 levels deep. 
When you use recursive macros, you call a macro from its own definition (the macro calls 
itself). 

When you create recursive or nested macros, you should pay close attention to the 
arguments that you pass to macro parameters because the assembler uses dynamic 
scoping for parameters. This means that the called macro uses the environment of the 
macro from which it was called. 

The following example shows nested macros. Note that the y in the in_block macro hides 
the y in the out_block macro. The x and z from the out_block macro, however, are accessible 
to the in_block macro. 


in_block .macro y,a 

; visible parameters are y,a and 
; X, z from the calling macro 

. endm 


out_block .macro x,y,z 

; visible parameters are x,y,z 

in_block x,y 

; macro call with x and y as 
; arguments 

. endm 


out_block 

; macro call 


Example 6.14: Using Nested Macros 
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The next example shows recursive macros. The fact macro produces assembly code 
necessary to calculate the factorial of n where n is an immediate value. The result is placed 
in the A register. The fact macro accomplishes this by calling fact1, which calls itself 
recursively. 



.fcnolist 


f actl 

.macro n 



.if n == 1 

mov #globcnt, R4 

; leave answer in R4 reg. 


. else 

.eval n-1, temp 

.eval globcnt*temp, globcnt 

factl temp 

; compute decrement of n 
; multiply to get new result 
; recursive call 


.endif 
. endm 


fact 

.macro n 



.if ! $iscons(n) 

.emsg "Farm not a constant" 

; type check input 


.elseif n < 1 
mov #0, R4 

; type check input 


. else 

.var temp 
.asg n, globcnt 



factl n 

; perform recursive procedute 


.endif 
. endm 



Example 6.15: Using Recursive Macros 
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6.10 Macro Directives Summary 


Creating Macros 


Mnemonic and Syntax 

Description 

macname .macro 
[parameter y ]... [parameter 

Define macro 

.mlib filename 

Identify library containing macro definitions 

.mexit 

Go to .endm 

.endm 

End macro definition 

Manipulating Substitution Symbols 

Mnemonic and Syntax 

Description 

.asg [“[character string[‘[, substitution 
symbol 

Assign character string to substitution 
symbol 

.eval well-defined expression, substitution 
symbol 

Perform arithmetic on numeric substitution 
symbols 

.var substitution symbol ^...[substitution 
symbol^] 

Define local macro symbols 

Conditional Assembly 

Mnemonic and Syntax 

Description 

.if well-defined expression 

Begin conditional assembly 

.elseif well-defined expression 

Optional conditional assembly block 

.else 

Optional conditional assembly block 

.endif 

End conditional assembly 

.loop [well-defined expression] 

Begin repeatable block assembly 

.break [well-defined expression] 

Optional repeatable block assembly 

.endloop 

End repeatable block assembly 
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Producing Assembly-Time Messages 



Mnemonic and Syntax 

Description 

.emsg 

Send error message to standard output 

.wmsg 

Send warning message to standard output 

.mmsg 

Send assembly-time message to standard 
output 


Formatting the Listing 


Mnemonic and Syntax 

Description 

.fclist 

Allow false conditional code block listing 
(default) 

.fcnolist 

Inhibit false conditional code block listing 

.mlist 

Allow macro listings (default) 

.mnolist 

Inhibit macro listings 

.ssiist 

Allow expanded substitution symbol listing 

.ssnolist 

Inhibit expanded substitution symbol listing 
(default) 
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7 Archiver Description 


The MSP430 family archiver lets you combine several individual files into a single file called 
an archive or a library. Each file within the archive is called a member. Once you have 
created an archive, you can use the archiver to add more files to the library, delete or replace 
existing members, or extract members. 

You can build libraries out of any type of files. Both the assembler and the linker accept 
archive libraries as input; the assembler can use libraries that contain individual source files, 
and the linker can use libraries that contain individual object files. 

One of the most useful applications of the archiver is to build a library of object modules. For 
example, you could write several arithmetic routines, assemble them, and then use the 
archiver to collect the object files into a single, logical group. You can then specify an object 
library as linker input. The linker will search through the library and include any members that 
resolve external references. 

You can also use the archiver to build macro libraries. You can create several separate 
source files, each of which contains a single macro, and then use the archiver to collect 
these macros into a single, functional group. The .mlib assembler directive lets you specify 
the name of a macro library to the assembler; during the assembly process, the assembler 
will search the specified library for the macros that you call. 


7-3 



Archiver Description 


MSP430 Famil 


7.1 Archiver Development Flow 

The figure shows the archiver's role in the assembly language development process. Both 
the assembler and the linker accept libraries as input. 



Figure 7.1 : Archiver Development Flow 
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7.2 Invoking the Archiver 

To invoke the archiver, enter: 


ar430 [-]command[option] libname [filename f ... filename^] 


ar430 is the command that invokes the archiver. 

libname names an archive library. If you don't specify an extension for libname, the 
archiver uses the default extension .lib. 

filename names individual member files that are associated with the library. If you don't 
specify an extension for a filename, the archiver uses the default extension .obj. 

command tells the archiver how to manipulate the members in the library. A command can 
be preceded by an optional hyphen. You must use one of the following 
commands when you invoke the archiver, but you can use only one command 
per invocation. These are valid archiver commands: 

-a adds the specified files to the library. Note that this command does not 
replace an existing member that has the same name as an added file; it 
simply appends new members to the end of the archive. It is possible to 
have several members with the same name in an archive. If you want to 
replace existing members, use the r command. 

-d deletes the specified members from the library. 

-r replaces the specified members in the library. If you don't specify any 
filenames, the archiver replaces the library members with files of the 
same name in the current directory. If the specified file is not found in the 
library, the archiver adds it instead of replacing it. 

-t prints a table of contents of the library. If you specify filenames, only 
those files are listed. If you don't specify any filenames, the archiver lists 
all the members in the specified library. 

-X extracts the specified files. If you don't specify any member names, the 
archiver extracts all the members in the library. When the archiver 
extracts a member, it simply copies the member into the current 
directory; it cfoesnY remove it from the library. 

In addition to one of the commands, you can specify the following options: 

-e tells the archiver not to use the default extension .obj for member names. 
This allows the use of filenames without extensions. 

-q (quiet) suppresses the banner and status messages. 

-s prints a list of the global symbols that are defined in the library. (This 

option is valid only with the -a, -r, and -d commands.) 

-V (verbose) provides a file-by-file description of the creation of a new 
library from an old library and its constituent members. 
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Note: Naming Library Members 

It is possible (but not desirable) for a library to contain several members with the same 
name. If you attempt to delete, replace, or extract a member, and the library contains more 
than one member with the specified name, the archiver deletes, replaces, or extracts the 
first member with that name. 
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7.3 Archiver Examples 

Here are some examples of using the archiver. 

• Example 1 

This example creates a library called function.lib that contains the files sine.obj, cos.obj, 
and fit.obj. 

ar430 -a function sine cos fit 

MSP430 Archiver Version 1.00 

Copyright (c) 1994 Texas Instruments Incorporated 
==> new archive 'function.lib' 

=: = > building archive ' function. lib ' 

Because these examples use the default extensions (.lib for the library and .obj for the 
members), it is not necessary to specify them. 

• Example 2 

You can print a table of contents of function.lib with the -t option; 

ar430 -t function 

MSP430 Archiver Version 1.00 

Copyright (c) 1994 Texas Instruments Incorporated 


FILE NAME 

SIZE 

DATE 




sine.obj 

248 

Mon 

Feb 

14 

01:25:44 

1994 

cos.obj 

248 

Mon 

Feb 

14 

01:25:44 

1994 

f1t.obj 

248 

Mon 

Feb 

14 

01:25:44 

1994 


• Example 3 

You can explicitly specify extensions if you don't want the archiver to use the default 
extensions; for example: 

ar430 -av function.fn sine.asm cos.asm fit.asm 
MSP430 Archiver Version 1.00 

Copyright (c) 1994 Texas Instruments Incorporated 
==> add 'sine.asm' 

==> add 'cos.asm' 

==> add 'fit.asm' 

==> building archive 'function.fn' 

This creates a library called function.fn that contains the files sine.asm, cos.asm, and 
fit.asm. (-V is the verbose option.) 

• Example 4 

If you want to add new members to the library, specify 

ar430 -as function tan.obj arctan.obj area.obj 
MSP430 Archiver Version 1.00 

Copyright (c) 1994 Texas Instruments Incorporated 
==> symbol defined: 'R2D2' 

==> symbol defined: 'Christmas' 

==> building archive 'function.lib' 

Because this example doesn't specify an extension for the libname, the archiver adds the 
files to the library called function.lib. If function.lib didn't exist, the archiver would create it. 
(The -s option tells the archiver to list the global symbols that are defined in the library.) 
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• Example 5 

If you want to modify a member in a library, you can extract it, edit it, and replace it. In 
this example, assume there's a library named macros.lib that contains the members 
push.asm, pop.asm, and swap.asm. 

ar430 -x macros push.asm 

The archiver makes a copy of push.asm and places it in the current directory; it doesn't 
remove push.asm from the library, though. Now you can edit the extracted file. To 
replace the copy of push.asm that's in the library with the edited copy, enter: 

ar430 -r macros push.asm 
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8 Linker Description 

The MSP430 family linker creates executable modules by combining COFF object files. The 
concept of COFF sections is basic to linker operation. 

As the linker combines object files, it: 

• allocates sections into the target system's configured memory 

• relocates symbols and sections to assign them to final addresses 

• resolves undefined external references between input files 

The linker command language controls memory configuration, output section definition, and 
address binding. The language supports expression assignment and evaluation and 
provides two powerful directives, MEMORY and SECTIONS, that allow you to: 

• define a memory model that conforms to target system memory 

• combine object file sections 

• allocate sections into specific areas of memory 

• define or redefine global symbols at link time 
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8.1 Linker Development Flow 

The following figure illustrates the linker's role in the assembly language development 
process. The linker accepts several types of files as input, including object files, command 
files, libraries, and partially linked files. The linker creates an executable COFF object 
module that can be downloaded to one of several development tools or executed by a 
MSP430 device. 
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8.2 Invoking the Linker 

The general syntax for invoking the linker is: 


Ink430 [-option] filenamei ... filenamefi 


Ink430is the command that invokes the linker. 
options 

can appear anywhere on the command line or in a linker command file. (Options are 
discussed in Section 8.3.) 

filenames 

can be object files, linker command files, or archive libraries. The default extension 
for all input files is .obj, any other extension must be explicitly specified. The linker 
can determine whether the input file is an object file or an ASCII file that contains 
linker commands. The default output filename is a.out 

There are three methods for invoking the linker: 

• Specify options and filenames on the command line. This example links two files, file1 .obj 
and file2.obj, and creates an output module named link.out. 

Ink430 filel.obj file2.obj -o link.out 

• Enter the Ink430 command with no filenames and no options; the linker will prompt for 
them: 

Command files : 

Object files [.obj] : 

Output files [ ] : 

Options : 

For command files, enter one or more command file names. 

For object files, enter one or more object file names. The default extension is .obj. 
Separate the filenames with spaces or commas; if the last character is a comma, the 
linker will prompt for an additional line of object file names. 

The output file is the name of the linker output module. This overrides any -o options 
entered with any of the other prompts. If there are no -o options and you do not answer 
this prompt, the linker will create an object file with a default filename of a.out. 

The options prompt is for additional options, although you can also enter them in a 
command file. Enter them with hyphens, just as you would on the command line. 

• Put filenames and options In a linker command file. For example, assume the file 
linker.cmd contains the following lines: 

-o link.out 
filel.obj 
file2.obj 

Now you can invoke the linker from the command line; specify the command file name as 
an input file: 
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lnk430 linker.cmd 

When you use a command file, you can also specify other options and files on the 
command line. For example, you could enter: 
lnk430 -m link.map linker.cmd file3.obj 

The linker reads and processes a command file as soon as it encounters it on the 
command line, so it links the files in this order; filel.obj, file2.obj, and fileS.obj. This 
example creates an output file called link.out and a map file called link.map. 
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8.3 Linker Options 

Linker options control linking operations. They can be placed on the command line or in a 
command file. Linker options must be preceded by a hyphen (-). The order in which options 
are specified is unimportant, except for the -I and -i options. Options are separated from 
arguments (if they have them) by an optional space. 


Option 

Description 

-a 

Produce an absolute, executable module. This is the default; if neither 
-a nor -r is specified, the linker acts as if -a is specified. 

-ar 

Produce a relocatable, executable object module. 

-e global symbol 

Define a global symbol that specifies the primary entry point for the 
output module. 

-f fill value 

Set the default fill value for holes within output sections; fill value is a 

16-bit constant. 

-h 

Make all global symbols static. 

-i dirt 

Alter the library-search algorithm to look in dir before looking in the 
default location. This option must appear before the -I option. 

-I filename f 

Name an archive library file as linker input; filename is an archive 
library name. 

-m filename t 

Produce a map or listing of the input and output sections, including 
holes, and place the listing in filename. 

-o filename t 

Name the executable output module. The default filename is a.out. 

-q 

Request a quiet run (suppress the banner). 

-r 

Retain relocation entries in the output module. 

-s 

Strip symbol table information and line number entries from the output 
module. 

-u symbol 

Place an unresolved external symbol into the output module's symbol 
table. 

-X 

Force rereading of libraries. Resolves “back" references. 

-z filename t 

Produce an additional byte formatted ASCII file loadable by the 
evaluation module. The default filename is the output filename with 
the extension .txt. 


t The filename must follow operating system conventions. 


Table 8.1 : Linker Options Summary 
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8.3.1 Relocation Capabilities (-a and -r Options) 

One of the tasks the linker performs is relocation. Relocation is the process of adjusting all 
references to a symbol when the symbol's address changes. The linker supports two options 
(-a and -r) that allow you to produce an absolute or a relocatable output module. Default is - 
a. 


• Producing an Absolute Output Module (-a Option) 

When you use the -a option without the -r option, the linker produces an absolute, 
executable output module. Absolute files contain no relocation information. Executable 
files contain the following: 

• special symbols defined by the linker 

• an optional header that describes information such as the program entry point 

• no unresolved references 

This example links filel .obj and file2.obj and creates an absolute output module called 
a.out: 

lnk430 -a filel.obj file2.obj 

• Producing a Relocatable Output Module (-r Option) 

When you use the -r option without the -a option, the linker retains relocation entries in 
the output module. If the output module will be relocated (at load time) or relinked (by 
another linker execution), use -r to retain the relocation entries. 

The linker produces an unexecutable file when you use the -r option without -a. A file that 
is not executable does not contain special linker symbols or an optional header. The file 
may contain unresolved references, but these references do not prevent creation of an 
output module. 

This example links filel.obj and flle2.obj and creates a relocatable output module called 
a.out: 

lnk430 -r filel.obj file2.obj 

The output file a.out can be relinked with other object files or relocated at load time. 
(Linking a file that will be relinked with other files is called partial linking) 

• Producing an Executable Relocatable Output Module (-ar) 

If you invoke the linker with both the -a and -r options, the linker produces an executable, 
relocatable object module. The output file contains the special linker symbols, an optional 
header, and all resolved symbol references, but the relocation information is retained. 

This example links filel .obj and file2.obj and creates an executable, relocatable output 
module called xr.out: 

lnk430 -ar filel.obj file2.obj -o xr.out 

Note that you can string the options together (Ink430 -ar) or you can enter them 
separately (Ink430 -a -r). 
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• Relocating or Relinking an Absolute Output Module 

The linker issues a warning message (but continues executing) when it encounters a file 
that contains no relocation or symbol table information. Relinking an absolute file can be 
successful only if each input file contains no information that needs to be relocated (that 
is, each file has no unresolved references and is bound to the same virtual address that it 
was bound to when the linker created it). 

8.3.2 Define an Entry Point (-e global symbol Option) 

The memory address that a program begins executing from is called the entry point. When 
a loader loads a program into target memory, the program counter must be initialized to the 
entry point; the PC then points to the beginning of the program. 

The linker can assign one of four possible values to the entry point. These values are listed 
below in the order in which the linker tries to use them. If you use one of the first three 
values, it must be an external symbol in the symbol table. Possible entry point values 
include: 

• The value specified by the -e option. The syntax is -e global symbol where global symbol 
defines the entry point and must appear as an external symbol in one of the input files. 

• Zero (default value). 


This example links filel.obj and fileZ.obj. The symbol begin is the entry point; begin must be 
defined as external in file1 orfileZ. 

Ink430 -e begin filel.obj file2.obj 

8.3.3 Set Default Fill Value (-f cc Option) 

The -f option fills the holes formed within output sections or initializes uninitialized sections 
when they are combined with initialized sections. This allows you to initialize memory areas 
during link time without reassembling a source file. The argument cc is a 16-bit constant (up 
to four hexadecimal digits). If you do not use -f, the linker uses 0 as the default fill value. 

This example fills holes with the hexadecimal value ABCD: 

lnk430 -f OABCDh filel.obj file2.obj 

8.3.4 Make All Global Symbols Static (-h Option) 

The -h option makes output global symbols static. This is useful when you are using partial 
linking to link related object files into self-contained modules, then relinking the modules 
together into a final system. If there are global symbols in one module that have the same 
name as global symbols in other modules, but you want to treat them as separate symbols, 
use the -h option when building the modules. The global symbols in the modules, which 
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would normally be visible to the other modules and cause possible redefinition problems in 
the final link, are made static so they are not visible to the other modules. 

For example, assume bl.obj, b2.obj, and bS.obj are related and reference a global variable 
GLOB. Also assume that dl.obj, d2.obj, and dS.obj are related and reference a separate 
global variable GLOB. You can link the related files together with the following commands: 

lnk430 -h -r bl.obj b2.obj bS.obj -o bpart.out 
lnk430 -h -r dl.obj d2.obj d3.obj -o dpart.out 

The -h option guarantees that bpart.out and dpart.out will not have global symbols and 
therefore two distinct versions of GLOB exist. The -r option is used to allow bpart.out and 
dpart.out to retain their relocation entries. These two partially linked files can then be linked 
together safely with the following command: 

lnk430 bpart.out dpart.out -o system.out 

8.3.5 Alter the Library Search Algorithm (-i c//r Option/C_DIR) 

Usually, when you want to specify a library as linker input, you simply enter the library name 
as you would any other input filename; the linker looks for the library in the current directory. 
For example, suppose the current directory contains the library object.lib. Assume that this 
library defines symbols that are referenced in the file filet .obj. This is how you link the files: 

lnk430 filel.obj object.lib 

If you want to use a library that is not in the current directory, use the -I (lowercase “L") linker 
option. The syntax for this option is -I filename. The filename is the name of an archive 
library; the space between -I and the filename is optional. 

You can augment the linker's directory search algorithm by using the -i linker option or the 
environment variable. The linker searches for object libraries in the following order: 

1) It searches directories named with the -i linker option. 

2) It searches directories named with the environment variable C_DIR. 

3) If C_DIR is not set, it searches directories named with the assembler's environment 
variable, A_DIR. 

4) It searches the current directory. 

-i Linker Options - 

The -i linker option names an alternate directory that contains object libraries. The syntax for 
this option is -i dir. dir names a directory that contains object libraries; the space between -i 
and the directory name is optional. When the linker is searching for object libraries named 
with the -I option, it searches through directories named with -i first. Each -i option specifies 
only one directory, but you can use several -i options per invocation. When you use the -i 
option to name an alternate directory, it must precede the -I option on the command line or in 
a command file. 


8-12 



MSP430 Family 


Linker Description 


As an example, assume that there are two archive libraries called r.lib and Iib2.lib. The table 
below shows the directories that r.lib and Iib2.lib reside in, how to set environment variable, 
and how to use both libraries during a link. 


- 1 

Pathname 

Invocation Command 

\ld and \ld2 

Ink430 fl.obj f2.obi -i\ld -i\ld2 -Ir.lib -Ilib2.lib 






Environment Variable (C_DIR) - 

An environment variable is a system symbol that you define and assign a string to. The linker 
uses an environment variable named C_DIR to name alternate directories that contain object 
libraries. The command for assigning the environment variable is: 

DOS set c_DiR=pathname;another pathname... 

The pathnames are directories that contain object libraries. Use the -I option on the 
command line or in a command file to tell the linker which libraries to search for. 

As an example, assume that two archive libraries called r.lib and Iib2.lib reside in Id and Id2 
directories. The table below shows the directories that r.lib and Iib2.lib reside in, how to set 
the environment variable, and how to use both libraries during a link. 


Pathname 

Invocation Command 

\ld and \ld2 

set C_DIR=\ld;\ld2 

lnk430 fl.obj f2.obj -1 r.lib -1 lib2.1ib 






Note that the environment variable remains set until you reboot the system or reset the 
variable by entering: 

DOS set C_DIR= 

The assembler uses an environment variable named A_DIR to name alternate directories 
that contain copy/include files or macro libraries. If C_DIR is not set, the linker will search for 
object libraries in the directories named with A_DIR. 
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8.3.6 Create a Map File (-m filename Option) 

The -m option creates a link map listing and puts it in filename. This map describes: 

• Memory configuration. 

• Input and output section allocation. 

• The addresses of external symbols after they have been relocated. 

The map file contains the name of the output module and the entry point; it may also contain 
up to three tables: 

• A table showing the new memory configuration if any nondefault memory is specified. 

• A table showing the linked addresses of each output section and the input sections that 
make up the output sections. 

• A table showing each external symbol and its address. This table has two columns: the 
left column contains the symbols sorted by name, and the right column contains the 
symbols sorted by address. 

This example links file1 .obj and file2.obj and creates a map file called map.out: 

lnk430 filel.obj file2.obj -m map.out 

8.3.7 Name an Output Module (-o filename Option) 

The linker creates an output module when no errors are encountered. If you do not specify 
a filename for the output module, the linker gives it the default name a.out. If you want to 
write the output module to a different file, use the -o option. The filename is the new output 
module name. 

This example links file1 .obj and file2.obj and creates an output module named run.out: 
lnk430 -o run.out filel.obj file2.obj 


8.3.8 Specify a Quiet Run (-q Option) 

The -q option suppresses the linker's banner when -q is the first option on the command line 
or in a command file. This option is useful for batch operation. 
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8.3.9 Strip Symbolic Information (-s Option) 

The -s option creates a smaller output module by omitting symbol table information and line 
number entries. The -s option is useful for production applications when you must create the 
smallest possible output module. 

This example links filel.obj and file2.obj and creates an output module, stripped off line 
numbers and symbol table information, named nosym.out: 

lnk430 -o nosym.out -s filel.obj file2.obj 

Note that using the -s option limits later use of a symbolic debugger and may prevent a file 
from being relinked. 

8.3.5 Introduce an Unresolved Symbol (-u symbo/Option) 

The -u option introduces an unresolved symbol into the linker's symbol table. This forces the 
linker to search through a library and include the member that defines the symbol. Note that 
the linker must encounter the -u option before it links in the member that defines the symbol. 

For example, suppose a library named rts.lib contains a member that defines the symbol 
symtab; none of the object files you are linking reference symtab. Suppose you plan to relink 
the output module, however, and you would like to include the library member that defines 
symtab in this link. Using the -u option as shown below forces the linker to search rts.lib for 
the member that defines symtab and to link in the member. 

Ink430 -u symtab filel.obj file2.obj rts.lib 

If you do not use -u, this member is not included, because there is no explicit reference to it 
in file1 .obj or file2.ob]. 

8.3.6 Exhaustively Read Libraries (-x option) 
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The linker normally reads input files, archive libraries included, only once: when they are 
encountered on the command line or in the command file. When an archive is read, any 
members that resolve references to undefined symbols are included in the link. If an input file 
later references a symbol defined in a previously read archive library (this is called a back 
reference), the reference will not be resolved. 

You can force the linker to repeatedly reread all libraries with the -x option. The linker will 
continue to reread libraries until no more references can be resolved. For example, if a.Iib 
contains a reference to a symbol defined in b.lib, and b.lib contains a reference to a symbol 
defined in a.Iib, you can resolve the mutual dependencies by listing one of the libraries twice, 
as in: 

lnk430 -la.lib -lb.lib -la.lib 

or you can force the linker to do it for you: 

lnk430 -X -la.lib -lb.lib 

Unking with the -x option may be slower, so you should use the option only as needed. 
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8.4 Command Files 

Linker command files allow you to put linking information in a file; this is useful when you 
often invoke the linker with the same information. Linker command files are also useful 
because they allow you to use the MEMORY and SECTIONS directives to customize your 
application. You must use these directives in a command file; you cannot use them on the 
command line. Command files are ASCII files that contain one or more of the following: 

• Input file names, which specify object files, archive libraries, or other command files. (If a 
command file calls another command file as input, this statement must be the last 
statement in the calling command file. The linker does not return from called command 
files.) 

• Linker options, which can be used in the command file in the same manner that they are 
used on the command line. 

• The MEMORY and SECTIONS linker directives. The MEMORY directive defines the 
target memory configuration. The SECTIONS directive controls how sections are built 
and allocated. 

• Assignment statements, which define and assign values to global symbols. 

To invoke the linker with a command file, enter the Ink430 command and follow it with the 
name of the command file: 

Ink430 command file name 

The linker processes input files in the order that it encounters them. If the linker recognizes a 
file as an object file, it links the file. Otherwise, it assumes that a file is a command file and 
begins reading and processing commands from it. 

The example shows a sample linker command file called link.cmd. 


/******************************************************************/ 
/* Sample Linker Command File */ 

a. obj /* First input filename */ 

b. obj /* Second input filename */ 

-o prog.out /* Option to specify output file */ 

-m prog.map /* Option to specify map file */ 


Example 8.1 : Linker Command File 

This sample file contains only filenames and options. (Note that you can place comments in 
a command file by delimiting them with /* and */.) To invoke the linker with this command file, 
enter: 

lnk430 link.cmd 

You can place other parameters on the command line when you use a command file: 

lnk430 -r link.cmd c.obj d.obj 


8-17 





Linker Description 


MSP430 Family 


The linker processes the command file as soon as it encounters it, so a.obj and b.ob] are 
linked into the output module before c.obj and d.obj. 

You can specify multiple command files. If, for example, you have a file called names.1st that 
contains filenames and another file called dir.cmd that contains linker directives, you could 
enter: 

lnk430 names.1st dir.cmd 

One command file can call another command file; this type of nesting is limited to 16 levels. 
If a command file calls another command file as input, this statement must be the last 
statement in the calling command file. 

Blanks and blank lines that appear in a command file are insignificant except as delimiters. 
This applies to the format of linker directives in a command file, also. The following example 
shows a sample command file that contains linker directives. (Linker directive formats are 
discussed in later sections.) 


/***************************************************************/ 
/* Sample Linker Command File with Directives */ 

/***************************************************************/ 
a.obj b.obj c.obj /* Input filenames */ 

-o prog.out -m prog.map /* Options */ 


MEMORY 

r 




... /* MEMORY directives 

i 

RAM: 

origin = 

200h 

length 

= OlOOh 

ROM: 

origin = 

OFOOOh 

length 

= lOOOh 


} 




SECTIONS 

{ 

.text: > ROM 

.data: > ROM 

.bss: > RAM 

} 


/* SECTION directives */ 


Example 8.2: Command File With Linker Directives 
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The following names are reserved as keywords for linker directives. Do not use them as 
symbol or section names in a command file. 


align 

GROUP 

origin 

ALIGN 

I (lowercase L) 

ORIGIN 

attr 

len 

page 

ATTR 

length 

PAGE 

block 

LENGTH 

range 

BLOCK 

load 

run 

COPY 

LOAD 

RUN 

□SECT 

MEMORY 

SECTIONS 

f 

NOLOAD 

spare 

FILL 

0 

type 

fill 

org 

TYPE 

group 


UNION 


Constants in Command Files- 

Constants can be specified with either of two syntax schemes: the scheme used for 
specifying decimal, octal, or hexadecimal constants used in the assember or the scheme 
used for integer constants in "C" syntax. 
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8.5 Object Libraries 

An object library is a partitioned archive file that contains complete object files as members. 
Usually, a group of related modules are grouped together Into a library. When you specify an 
object library as linker input, the linker includes any members of the library that define 
existing unresolved symbol references. You can use the MSP430 archiver to build and 
maintain libraries. 

Using object libraries can reduce link time and can reduce the size of the executable module. 
If a normal object file that contains a function Is specified at link time, it is linked whether it is 
used or not; however, if that same function is placed in an archive library, it is included only if 
it is referenced. 

The order in which libraries are specified is important because the linker includes only those 
members that resolve symbols that are undefined when the library is searched. The same 
library can be specified as often as necessary; it is searched each time it is included, or the - 
X option may be used. A library has a table that lists all external symbols defined in the 
library; the linker searches through the table until it determines that it cannot use the library 
to resolve any more references. 

This example links several files and libraries. Assume the following: 

• Input files f1 .obj and f2.obj both reference an external function named cirscr. 

• Input file f1 .obj references the symbol origin. 

• Input file f2.obj references the symbol fillcir. 

• Library libc.lib, member 0, contains a definition of origin. 

• Library liba.Iib, member 3, contains a definition of fillcir. 

• Member 1 of both libraries defines cirscr. 

If you enter Ink430 fl.obj liba.Iib f2.obj libc.lib: 

• Member 1 of liba.Iib satisfies both references to cirscr because the library is searched 
and cirscr is defined before f2.obj references it. 

• Member 0 of libc.lib satisfies the reference to origin. 

• Member 3 of liba.Iib satisfies the reference to fillcir. 

If, however, you enter Ink430 fl.obj f2.obj libc.lib liba.Iib, the references to cirscr are satisfied 
by member 1 of libc.lib. 

If none of the linked files reference symbols defined in a library, you can use the -u option to 
force the linker to include a library member. The next example creates an undefined symbol 
rout1 in the linker's global symbol table: 

lnk430 -u routl libc.lib 
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If any members of libc.lib define rout1, the linker includes those members. Note that it is not 
possible to control the allocation of individual library members; members are allocated 
according to the SECTIONS directive default allocation algorithm. 
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8.6 The MEMORY Directive 

The linker determines where output sections should be allocated into memory; the linker 
must have a model of target memory to accomplish this task. The MEMORY directive allows 
you to specify a model of target memory so that you can define the types of memory your 
system contains and the address ranges they occupy. The linker maintains the model as it 
allocates output sections and uses the model to determine which memory locations can be 
used for object code. 

The memory configurations of MSP430 systems differ from application to application. The 
MEMORY directive allows you to specify a variety of configurations. After you use the 
MEMORY directive to define a memory model, you can use the SECTIONS directive to 
allocate output sections into defined memory. 

8.6.1 Default Memory Model 

The linker's default memory model is based on the MSP430 architecture. This model 
assumes that the following memory is available: 

• 256 bytes of RAM, beginning at location 200h 

• 4K bytes of ROM, beginning at location OFOOOh. 

If you do not use the MEMORY directive, the linker uses this default memory model. 

8.6.2 MEMORY Directive Syntax 

The MEMORY directive identifies ranges of memory that are physically present in the target 
system and can be used by a program. Each range of memory has several characteristics: 

• Name 

• Starting address 

• Length 

• Optional set of attributes 

• Optional fill specification 

When you use the MEMORY directive, be sure to identify all the memory ranges that are 
available to load code into. Any memory that you do not explicitly account for with the 
MEMORY directive is unconfigured. The linker does not place any part of a program into 
unconfigured memory. You can represent nonexistent memory spaces by simply not 
including an address range in a MEMORY directive statement. 


8-22 





MSP430 Family 


Linker Description 


The MEMORY directive is specified in a command file by the word MEMORY (uppercase), 
followed by a list of memory range specifications enclosed in braces. For example, you could 
use the MEMORY directive to specify a memory configuration as follows: 

/**********************************************************/ 

/* Sample command file with MEMORY directive */ 

filel.obj file2.obj /* Input files */ 

-o prog.out /* Options */ 


MEMORY 

{ 

RAM: origin = 200h length = lOOh 

ROM: origin = OFOOOh length = lOOOh 

} 


You could then use the SECTIONS directive to link the .bss section into the memory area 
named RAM, .text into ROM, and .data into ROM. 

The general syntax for the MEMORY directive is: 

MEMORY 

{ 

name 1 [(attr)]: origin = constant, length = constant, fill = constant 


name n [(attr)]: origin = constant, length = constant, fill = constant 

} 

name Names a memory range. A memory name may be 1 to 8 characters; valid characters 
include A-Z, a-z, $, ., and _. The names have no special significance to the linker; 
they simply identify memory ranges. Memory range names are internal to the linker 
and are not retained in the output file or in the symbol table. 

attr Specifies 1 to 4 attributes associated with the named range. Attributes are optional; 
when used, they must be enclosed in parentheses. Attributes can restrict the 
allocation of output sections into certain memory ranges. If you do not use any 
attributes, you can allocate any output section into any range with no restrictions. Any 
memory for which no attributes are specified (including all memory in the default 
model) has all four attributes. Valid attributes include: 

R Specifies that the memory can be read. 

W Specifies that the memory can be written to. 

X Specifies that the memory can contain executable code. 

I Specifies that the memory can be initialized. 

origin Specifies the starting address of a memory range and may be abbreviated as org or 
o. The value, specified in bytes, is a long integer constant and may be decimal, octal, 
or hexadecimal. 
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length Specifies the length of a memory range and may be abbreviated as len or /. The 
value, specified in bytes, is a long integer constant and may be decimal, octal, or 
hexadecimal. 

fill Specifies a fill character for the memory range and may be abbreviated as f. Fills are 
optional. The value is a two-byte integer constant and may be decimal, octal, or 
hexadecimal. The fill value will be used to fill any areas of the memory range that are 
not allocated to a section. 


Note: Filling Memory Ranges 

If you specify fill values for large memory ranges, your output file will be very large 
because filling a memory range (even with zeros) causes raw data to be generated for all 
unallocated blocks of memory in the range. 


The following example specifies a memory range with the R and W attributes and a fill 
constant of OFFFFh: 

MEMORY 

{ 

RFILE (RW) : o = 02h, 1 = OFEh, f = OFFFFh 

} 

You normally use the MEMORY directive in conjunction with the SECTIONS directive to 
control allocation of output sections. After you use the MEMORY directive to specify the 
target system's memory model, you can use the SECTIONS directive to allocate output 
sections into specific named memory ranges or into memory that has specific attributes. 
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8.7 The SECTIONS Directive 

The SECTIONS directive tells the linker how to combine sections from input files into 
sections in the output module and where to place the output sections in memory. In 
summary, the SECTIONS directive: 

• Describes how input sections are combined into output sections. 

• Defines output sections in the executable program. 

• Specifies where output sections are placed in memory (in relation to each other and to 
the entire memory space). 

• Permits renaming of output sections. 

8.7.1 Default Sections Configuration 

If you do not specify a SECTIONS directive, the linker uses a default algorithm for combining 
and allocating the sections. 

8.7.2 SECTIONS Directive Syntax 

The SECTIONS directive is specified in a command file by the word SECTIONS (uppercase), 
followed by a list of output section specifications enclosed in braces. 

The general syntax for the SECTIONS directive is: 

SECTIONS 

{ 

name : [ property, property, property ,... ] 
name : [ property, property, property ,... ] 
name : [ property, property, property ,... ] 

} 

Each section specification, beginning with name, defines an output section. (An output 
section is a section in the output file.) After the section name is a list of properties that define 
the section's contents and how it is allocated. The properties may be separated by optional 
commas. Possible properties for a section are: 

load allocation defines where in memory the section is to be loaded. 

Syntax: load = allocation or 

allocation or 

> allocation 

run allocation defines where in memory the section is to be run. 

Syntax: run = allocation or 

run > allocation 

input sections defines the input sections composing the section. 

Syntax: {input_sections} 
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section type defines flags for special section types. 

Syntax: type = COPY or 

type = DSECT or 

type = NOLOAD 

For more information on section types, see Section 8.12. 

fill value defines the value used to fill uninitialized "holes" 

Syntax; fill = value or 

name: ... {...} = value 

For more information on creating and filling holes, see Section 8.14. 

The example shows a SECTIONS directive in a sample linker command file. The figure on 

the next page shows how these sections are allocated in memory. 



Example 8.3: The SECTIONS Directive 
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The figure shows the five output sections defined by the sections directive in the last 
example; .vectors, .text, .const, .bss, and .data. 



- bound at OFFEOh 

- allocated in ROM 


The .vectors section is composed of the 
.intved section from tl.obj and the .intvec2 
section from t2.obj. 

The .text section combines the .text sections 
from file1 .obj and file2.obj. The linker combines 
all sections named .text into section. 

The .const section combines the .const sec¬ 
tions from file1 .obj and file2.obj. The application 
must relocate the section to run at ODOOOh. 


- allocated in RAM 


The .bss section combines the .bss sections 
from file1 .obj and file2.obj 


- aligned on 16-byte boundary 

The .data section combines the .data sections 
from filel .obj and file2.obj. The linker will place it 
anywhere there is space for it (in RAM in this 
illustration) and align it to a 16-byte boundary. 



Figure 8.2: Section Allocation 
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8.7.3 Specifying the Address of Output Sections (Allocation) 

The linker assigns each output section two locations in target memory: the location where 
the section will be loaded and the location where it will be run. Usually, these are the same, 
and you can think of each section as having only a single address. In any case, the process 
of locating the output section in the target's memory and assigning its address(es) is called 
allocation. 

If you do not tell the linker how a section is to be allocated, it uses a default algorithm to 
allocate the section. Generally, the linker puts sections wherever they fit into configured 
memory. You can override this default allocation for a section by defining it within a 
SECTIONS directive and providing instructions on how to allocate it. 

You control allocation by specifying one or more allocation parameters. Each parameter 
consists of a keyword, an optional equals sign or greater-than sign, and a value optionally 
enclosed in parentheses. If load and run allocation is separate, all parameters following the 
keyword LOAD apply to load allocation, and those following RUN apply to run allocation. 
Possible allocation parameters are: 

binding allocates a section at a specific address 

.text: load = 0x1000 

memory allocates the section into a range defined in the MEMORY directive with the 
specified name or attributes 

.text: load > ROM 

alignment specifies that the section should start on an address boundary 

.text: align = 0x100 

blocking specifies that the section must fit between two address boundaries: for 
example, on a single data page. 

.text: block(OxlOO) 

For the load (usually the only) allocation, you may simply use a greater-than sign and omit 
the LOAD keyword: 

.text: > ROM .text: {...} > ROM 

.text: > 0x4000 

If more than one parameter is used, you can string them together as follows: 

.text: > ROM align 16 


Or if you prefer, use parentheses for readability: 

.text: load = (ROM align(16)) 

Binding- 

You can supply a specific starting address for an output section by following the section 
name with an address: 

.text: 0x4000 
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This example specifies that the .text section must begin at location 4000h. The binding 
address must be a 16-bit constant. 

Output sections can be bound anywhere in configured memory (assuming there is enough 
space), but they cannot overlap. If there is not enough space to bind a section to a specified 
address, the linker issues an error message. 


Note: Binding and Alignment or Named Memory Are incompatible 

You cannot bind a section to an address if you use alignment or named memory. If you try 
to do this, the linker issues an error message. 


Memory- 

You can allocate a section into a memory range that is defined by the MEMORY directive. 
This example names ranges and links sections into them: 

MEMORY 
{ 

ROM (RIX) : 

RAM (RWIX): 

} 

SECTIONS 
{ 

.text : > 

.data : > 

.bss : > 

} 

In this example, the linker places .text into the area called ROM. The .data and .bss output 
sections are allocated into RAM. You can align a section within a named memory range; the 
.data section is aligned on a 64-word boundary within the RAM range. 

Similarly, you can link a section into an area of memory that has particular attributes. To do 
this, specify a set of attributes (enclosed in parentheses) instead of a memory name. Using 
the same MEMORY directive declaration, you can specify: 

SECTIONS 

{ 


text : 

> 

(X) 

/* 

. text 

--> 

executable memory 

*/ 

data: 

> 

(RI) 

/* 

. data 

--> 

read or init memory 

*/ 

bss : 

> 

(RW) 

/* 

.bss 

--> 

read or write memory 

*/ 


} 

In this example, the .text output section can be linked into either the ROM or RAM area 
because both areas have the X attribute. The .data section can also go into either ROM or 
RAM because both areas have the R and I attributes. The .bss output section, however, 
must go into the RAM area because only RAM is declared with the W attribute. 


origin = Oh, length = lOOOh 

origin = ODOOOh, length = lOOOh 


ROM 

RAM, ALIGN=64 

RAM 
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You cannot control where in a named memory range a section is allocated, although the 
linker uses lower memory addresses first and avoids fragmentation when possible. In the 
preceding examples, assuming no other sections had been bound to addresses that would 
interfere with this allocation process, the .text section would start at address 0. If a section 
must start on a specific address, use binding instead of named memory. 

Alignment and Blocking- 

You can tell the linker to place an output section at an address that falls on an n-byte 
boundary, where n is a power of 2. For example: 

.text: load = align(32) 

allocates .text so that it falls on a 32-byte boundary. 

Blocking is a weaker form of alignment that places a section so that it is allocated anywhere 
within a “block" of size n. As with alignment, n must be a power of 2. For example: 

bss: load = block(0x1000) 

allocates .bss so that the entire section is contained in a single 4K-byte data page. 

You can use alignment or blocking alone or in conjunction with a memory area, but 
alignment and blocking cannot be used together. 

8.7.4 Specifying Input Sections 

An input section specification identifies the sections from input files that are combined to 
form an output section. The linker combines input sections by concatenating them in the 
order specified. The size of an output section is the sum of the sizes of the input sections that 
make up the output section. 


SECTIONS 

{ 

. text 
. data 
.bss 


Example 8.4: The Most Common Method of Specifying Section Contents 

The linker takes all the .text sections from the input files and combines them into the .text 
output section. The linker concatenates the .text input sections in the order that it encounters 
them in the input files. The linker performs similar operations with the .data and .bss 
sections. You can use this type of specification for any output section. 
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You can explicitly specify the input sections that form an output section. Each input section is 
identified by its filename and section name: 


SECTIONS 

{ 

.text : 

{ 

f1.obj(.text) 
f2.obj(seel) 
f3.obj 

f4.obj(.text,sec2) 

} 

} 


/* Build .text output section 

/* Link .text section from fl.obj 
/* Link seel section from f2.obj 
/* Link ALL sections from fS.obj 
/* Link .text and sec2 from f4.obj 


*/ 

V 

*/ 

*/ 


Note that it is not necessary for an input section to have the same name as another it is 
combined with or as the output section it becomes part of. If a file is listed with no sections, 
all of its sections are included in the output section. If any additional input sections have the 
same name as an output section but are not explicitly specified by the SECTIONS directive, 
they are automatically linked in at the end of the output section. For example, if the linker 
found more .text sections in the preceding example and these .text sections were not 
specified anywhere in the SECTIONS directive, the linker would concatenate these extra 
sections after f4.obj(sec2). 

The specifications in the example on the page before are actually a shorthand method for the 
following: 

SECTIONS 

{ 

. text: { * ( . text) } 

.data: { *( . data) } 

.bss: { *(.bss) } 

} 


The *(.text) means the unallocated .text sections from all the input files. This format is useful 
when: 


• You want the output section to contain all input sections that have a certain name, but the 
output section name is different from the input sections' names. 

• You want the linker to allocate the input sections before it processes additional input 
sections or commands within the braces. 


Here's an example that uses this method: 


SECTIONS 

r 


1 

.text : { 

abc.obj(xqt) 


*(.text 

} 


.data : { 

*(.data) 
fil.obj(table 
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In this example, the .text output section contains a named section xqt from file abc.obj, which 
is followed by all the .text input sections. The .data section contains all the .data input 
sections, followed by a named section table from the file fil.obj. Note that this method 
includes all the unallocated sections. For example, if one of the .text input sections was 
already included in another output section when the linker encountered *(.text), the linker 
could not include that first .text input section in the second output section. 
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8.8 Specifying a Section's Runtime Address 

It may be necessary or desirable at times to load code into one area of memory and run it in 
another. For example, you may have performance-critical code in a ROM-based system. 
The code must be loaded into ROM but would run much faster if it were in RAM. 

The linker provides a simple way to specify this. In the SECTIONS directive, you can 
optionally direct the linker to allocate a section twice: once to set its load address and again 
to set its run address. For example: 

.fir: load = ROM, run = RAM 

Use the /oad keyword for the load address and the run keyword for the run address. 

8.8.1 Specifying Two Addresses 

The load address determines where a loader will place the raw data for the section. Any 
references to the section (such as labels in it) refer to its run address. The application must 
copy the section from its load address to its run address; this does not happen automatically 
just by specifying a separate run address. 

If you provide only one allocation (either load or run) for a section, the section is allocated 
only once and will load and run at the same address. If you provide both allocations, the 
section is actually allocated as if it were two different sections of the same size. This means 
that both allocations occupy space in the memory map and cannot overlay each other or 
other sections. (The UNION directive provides a way to overlay sections) 

If either the load or run address has additional parameters, such as alignment or blocking, 
list them after the appropriate keyword. After the keyword load, everything having to do with 
allocation affects the load address until the keyword run is seen, after which everything 
affects the run address. The load and run allocations are completely independent, so any 
qualification of one (such as alignment) has no effect on the other. You may also specify run 
first, then load. Use parentheses to improve readability. Examples: 

.data: load = ROM, align = 32, run = RAM 

(align applies only to load ) 

.data: load = (ROM align 32), run = RAM 

(identical to previous example) 

.data: run = RAM, align 32, 

load = align 16 

(align 32 in RAM for run; align 16 anywhere for load) 
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8.8.2 Uninitialized Sections 

Uninitialized sections (such as .bss) are not loaded, so the only address of significance is the 
run address. The linker allocates uninitialized sections only once. If you specify both run and 
load addresses, the linker warns you and ignores the load address. Otherwise, if you specify 
only one address, the linker treats it as a run address, regardless of whether you call it load 
or run. Examples: 

.bss: load = 0x1000, run = RAM 

A warning is issued, load is ignored, space is allocated in RAM. All of the following examples 
have the same effect. The .bss section is allocated In RAM. 

.bss: load = RAM 
.bss: run = RAM 
.bss: > RAM 

8.8.3 Referring to the Load Address by Using the .label Directive 

Any reference to a normal symbol in a section refers to its runtime address. However, it may 
be necessary at runtime to refer to a load-time address. In particular, the code that copies a 
section from its load address to its run address must know where it was loaded. The .label 
directive in the assembler defines a special type of symbol that refers to the load address of 
the section. Thus, whereas normal symbols are relocated with respect to the run address, 
.label symbols are relocated with respect to the load address. 
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define a section to be copied from ROM to RAM 


.sect ".fir" 
.label fir_load 


<code here> 
ret 


; load address of section 
; run address of section 
; code for the section 


.label fir_end 

fir_len .equ fir_end - fir_load 


copy .fir section from ROM into RAM 



. text 




MOV 

#f ir_ 

_len, R4 


MOV 

#fir 

.load, R5 


MOV 

#fir. 

R6 


JMP 

L2 


Ll : 

MOV 

@R5+, 

0 (R6) 


INCD 

R6 


L2 : 

DECD 

R4 



JC 

Ll 



jump to section, now in RAM 
call fir 


; call runtime address 


Linker Command File 


/* PARTIAL LINKER COMMAND FILE FOR FIR EXAMPLE 
/**********■************************************ 
MEMORY 
{ 

ROM: origin=4000h length = 4000h 

RAM: origin=2000h length = 2000h 


.text: load = ROM 

.fir: load = ROM, run = RAM 



Example 8.5: Copying a Section From ROM to RAM 
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The figure illustrates the runtime execution of the last example. 



Figure 8.3: Runtime Execution 
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8.9 Using UNION and GROUP Statements 

Two SECTIONS statements allow you to conserve memory: GROUP and UNION. Unioning 
output sections causes the linker to allocate the same run address to the sections. Grouping 
output sections causes the linker to allocate them contiguously in memory. 

8.9.1 Overlaying Sections With the UNION Statement 

For some applications, you may wish to allocate more than one section to run at the same 
address: for example, you may have several routines you want in on-chip RAM at various 
stages of the program's execution. Or you may want several data objects that you know will 
not be active at the same time to share a block of memory. The UNION statement within the 
SECTIONS directive provides a way to allocate several sections at the same run address. 


SECTIONS 


. text: 

load 

= ROM 




UNION: 

run 

= RAM 




{ 


.bssl: 

{ filel.obj( 

.bss) 

} 



.bss2 : 

{ file2.obj( 

.bss) 

} 

1 

. bss3: 

run = 

RAM { 

globals.obj( 

.bss) 

} 


Example 8.6: Illustration of the Form of the UNION Statement 
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Figure 8.4: Runtime Memory Allocation 

In the example on the page before, the .bss sections from file1 .obj and file2.obj are allocated 
at the same address in RAM. The union occupies as much space in the memory map as its 
largest component. The components of a union remain independent sections; they are 
simply allocated together as a unit. 

Allocation of a section as part of a union affects only its run address. Under no 
circumstances can sections be overlaid for loading. If an initialized section is a union 
member (an initialized section has raw data, such as .text), its load allocation must be 
separately specified. The next example illustrates this. 
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UNION run 

= RAM 




1 

.textl 

load = 

ROM, 

{ filei.obj(.text) 

} 

.text2: 

) 

load = 

ROM, 

{ file2.obj(.text) 

} 


Example 8.7: Illustration of Separate Load Addresses for UNION Sections 



Since the .text sections contain data, they cannot load as a union, although they can be run 
as a union. Therefore, each requires its own load address. If you fail to provide a load 
allocation for an initialized section within a UNION, the linker issues a warning and allocates 
load space anywhere it fits in configured memory. 

Uninitialized sections are not loaded and do not require load addresses. 
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The UNION statement applies only to allocation of run addresses, so it is redundant to 
specify a load address for the union itself. For purposes of allocation, the union is treated as 
an uninitialized section: any one allocation specified is considered a run address, and, if both 
are specified, the linker issues a warning and ignores the load address. 


8.9.2 Grouping Output Sections Together 


The SECTIONS directive has a GROUP option that forces several output sections to be 
allocated contiguously. For example, assume that a section named term_rec contains a 
termination record for a table in the .data section. You can force the linker to allocate .data 
and fer/7?_rec together: 


SECTIONS 

{ 

. text 
.bss 

GROUP 100Oh : 

{ 

. data 
term_rec 

} 

} 


/* Normal output section */ 
/* Normal output section */ 
/* Specify a group of sections */ 

/* First section in the group */ 
/* Allocated immediately after .data */ 


You can use binding, alignment, or named memory to allocate a GROUP in the same way a 
single output section is allocated. In the preceding example, the GROUP is bound to address 
1000h. This means that .data is allocated at 1000h, and term_recto\\o\NS it in memory. 


Note: You Cannot Specify Addresses for Sections Within a Group 

When you use the GROUP option, binding, alignment, or allocation into named memory 
can be specified for the group only. You cannot use binding, named memory, or alignment 
for sections within a group. 
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8.11 Default Allocation Algorithm 

The MEMORY and SECTIONS directives provide flexible methods for building, combining, 
and allocating sections. Any memory locations or sections that you choose not to specify, 
however, must still be handled by the linker. The linker uses default algorithms to build and 
allocate sections within the specifications you supply. 

8.11.1 Default Allocation 

If you do not use any MEMORY or SECTIONS directives, the linker acts as though the 
following definitions were specified: 


MEMORY 

{ 


RAM : 

origin = 

200h 

length = 

lOOh 

ROM : 

1. 

origin = 

OFOOOh 

length = 

lOOOh 

; 

SECTIONS 

r 






1 

.bss : 

> 

RAM 




.text : 

> 

ROM 




.data : 

> 

ROM 





} 


All .bss input sections are concatenated to form one .bss output section linked into. All .data 
input sections are combined to form a .data output section, which is linked into ROM. All .text 
input sections are concatenated to form a .text output section, which is linked into ROM 
starting at location OFOOOh. 

Unless you specify otherwise with a MEMORY directive, the linker assumes the configuration 
specified above. That is, the only memory that the linker uses to build your program is: 

• 256 bytes starting at location 0200h, 

• 4K bytes starting at location OFOOOh. 

If there are additional input sections in the input files (specifically, named sections), the linker 
links them in after the default sections have been linked. Input sections that have the same 
name are combined into a single output section with this name. The linker allocates these 
additional output sections into memory wherever there is room. Usually, it is desirable to use 
explicit SECTIONS directives to tell the linker where to place named sections. 


Note: The SECTIONS Directive 

If a SECTIONS directive is specified, the linker performs no part of the default allocation. 
Allocation is performed according to the rules specified by the SECTIONS directive and 
the general algorithm described below. 
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8.11.2 General Rules for Forming Output Sections 

An output section can be formed in one of two ways: 

Rule 1 As the result of a SECTIONS directive definition. 

Rule 2 By combining input sections with the same names into output sections that are not 
defined in a SECTIONS directive. 

If an output section is formed as a result of a SECTIONS directive (rule 1), this definition 
completely determines the section's contents. 

An output section can also be formed when input sections are encountered that are not 
specified by any SECTIONS directive (rule 2). In this case, the linker combines all such input 
sections that have the same name into an output section with this name. For example, 
suppose the files fl.obj and f2.obj both contain named sections called Vectors and that the 
SECTIONS directive does not define an output section to contain them. The linker combines 
the two Vectors sections from the input files Into a single output section named Vectors, 
allocates it into memory, and includes it in the output file. 

After the linker determines the composition of all the output sections, it must allocate them 
into configured memory. The MEMORY directive specifies which portions of memory are 
configured, or if there is no MEMORY directive, the linker uses the default configuration. 

The linker's allocation algorithm attempts to minimize memory fragmentation. This allows 
memory to be used more efficiently and increases the probability that your program will fit 
into memory. This is the algorithm: 


1) Output sections for which you have supplied a specific binding address are placed in 
memory at that address. 

2) Output sections that are included In a specific, named memory range or that have 
memory attribute restrictions are allocated. Each output section is placed into the first 
available space within the named area, considering alignment where necessary. 

3) 0utput sections that have zero length are allocated at the beginning of the first 
appropriate memory area unless they are part of a group. 

4) Any remaining sections are allocated in the order In which they are defined. Sections not 
defined in a SECTIONS directive are allocated in the order in which they are 
encountered. Each output section is placed into the first available memory space, 
considering alignment where necessary. 
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8.12 Special Section Types (DSECT, COPY, and NOLOAD) 

You can assign three special types to output sections; DSECT, COPY, and NOLOAD. These 
types affect the way that the program is treated when it is linked and loaded. For example: 

SECTIONS 

{ 

seel: load = 2000h, type = DSECT {fl.obj} 

sec2: load = 4000h, type = COPY {f2.obj} 

sec3: load = 6000h, type = NOLOAD {f3.obj} 

} 

• The DSECT type creates a “dummy section" that has the following qualities: 

• It is not included in the output section memory allocation. It takes up no memory and 
is not included in the memory map listing. 

• It can overlay other output sections, other DSECTs, and unconfigured memory. 

• Global symbols defined in a dummy section are relocated normally. They appear in 
the output module's symbol table with the same value they would have if the DSECT 
had actually been loaded. These symbols can be referenced by other input sections. 

• Undefined external symbols found in a DSECT cause specified archive libraries to be 
searched. 

• The section's contents, relocation information, and line number information are not 
placed in the output module. 

In the preceding example, none of the sections from fl.obj are allocated, but all the 
symbols are relocated as though the sections were linked at address 2000h. The other 
sections can refer to any of the global symbols in seel. 

• A COPY section is similar to a DSECT section, except that its contents and associated 
information are written to the output module. 

• A NOLOAD section differs from a normal output section in one respect: the section's 
contents, relocation information, and line number information are not placed in the output 
module. The linker allocates space for it, it appears in the memory map listing, etc. 
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8.13 Assigning Symbols at Link Time 

Linker assignment statements allow you to define external (global) symbols and assign 
values to them at link time. You can use this feature to initialize a variable or pointer to an 
allocation-dependent value. 


8.13.1 Syntax of Assignment Statements 


The syntax of assignment statements in the linker is similar to that of assignment statements 
in the C language: 


symbol 

= 

expression; 

symbol 

+ = 

expression; 

symbol 

- = 

expression; 

symbol 

* _ 

expression; 

symbol 

/ = 

expression; 


assigns the value of expression to symbol 
adds the value of expression to symbol 
subtracts the value of expression from symbol 
multiplies symbol by expression 
divides symbol by expression 


The symbol should be defined externally in the program. If it is not, the linker defines a new 
symbol and enters it into the symbol table. Assignment statements must be terminated with 
a semicolon. 


The linker processes assignment statements after it allocates all the output sections. 
Therefore, if an expression contains a symbol, the address used for that symbol reflects the 
symbol's address in the executable output file. 

For example, suppose a program reads data from one of two tables identified by two external 
symbols, Tablel and Table2. The program uses the symbol cur_tab as the address of the 
current table. cur_tab must point to either Tablel or Table2. You could accomplish this in the 
assembly code, but you would need to reassemble the program in order to change tables. 
Instead, you can use a linker assignment statement to assign cur_tab at link time: 

prog.obj /* Input file */ 

cur_tab = Tablel; /* Assign cur_tab to one of the tables */ 


8.13.2 Assigning the SPC to a Symbol 

A special symbol, denoted by a dot (.), represents the current value of the SPC during 
allocation. The linker's “ . " symbol is analogous to the assembler's "$" symbol. The “ . " 
symbol can be used only in assignment statements within a SECTIONS directive because “ 
." is meaningful only during allocation, and SECTIONS controls the allocation process. 

For example, suppose a program needs to know the address of the beginning of the .data 
section. By using the .global directive, you can create an external undefined variable called 
□start in the program. Then, assign the value of to Dstart: 
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SECTIONS 

{ 

.text: {} 

.data: { Dstart = .; } 

.bss: {} 

} 

This defines Dstart to be the ultimate linked address of the .data section, (dstart is assigned 
before .data is allocated.) The linker will relocate all references to Dstart. 

A special type of assignment assigns a value to the symbol. This adjusts the location 
counter within an output section and creates a hole between two input sections. Any value 
assigned to to create a hole is relative to the beginning of the section, not to the address 
actually represented by 

8.13.3 Assignment Expressions 

These rules apply to linker expressions: 

• Expressions can contain global symbols, constants, and the C language operators listed 
in the next table. 

• All numbers are treated as long (32-bit) integers. 

• Constants are identified by the linker in the same manner as they are by the assembler. 
That is, numbers are recognized as decimal unless they have a suffix (H or h for 
hexadecimal and Q or q for octal). C language prefixes are also recognized (0 for octal 
and Ox for hex). Hexadecimal constants must begin with a digit. No binary constants are 
allowed. 

• Symbols within an expression have only the value of the symbol's address. No type¬ 
checking is performed. 

• Linker expressions can be absolute or relocatable. If an expression contains any 
relocatable symbols (and zero or more constants or absolute symbols), it is relocatable. 
Otherwise, the expression is absolute. If a symbol is assigned the value of a relocatable 
expression, the symbol is relocatable; if it is assigned the value of an absolute 
expression, the symbol is absolute. 

The linker supports the C language operators listed in the table in order of precedence. 
Operators in the same group have the same precedence. Besides the operators listed in the 
table, the linker also has an align operator that allows a symbol to be aligned on an n-byte 
boundary within an output section (n is a power of 2). For example, the expression 

. = align{16); 

aligns the SPC within the current section on the next 16-byte boundary. Because the align 
operator is a function of the current SPC, It can be used only in the same context as — 
that is, within a SECTIONS directive. 
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Group 1 (Highest Precedence) 

Group 6 

! 

Logical not 

& 


Bitwise AND 


Bitwise not 




- 

Negative 




Group 2 

Group 7 

* 

Multiplication 

1 


Bitwise OR 

/ 

Division 




% 

Mod 




Group 3 

Group 8 

+ 

Addition 

&& 


Logical AND 

- 

Minus 




Group 4 

Group 9 

» 

Arithmetic right shift 

II 


Logical OR 

« 

Arithmetic left shift 




Group 5 

Group 10 (Lowest Precedence) 

== 

Equal to 

= 


Assignment 

! = 

Not equal to 

+ = 


A+=B ®A=A+B 

> 

Greater than 



A- = B ® A = A-B 

< 

Less than 

* = 


A* = B® A = A*B 

< = 

Less than or equal to 

/ = 


A/ = B ® A = A/B 

> = 

Greater than or equal to 





Table 8.2: Operators in Assignment Expressions 

8.13.4 Symbols Defined by the Linker 

The linker automatically defines several symbols that a program can use at runtime to 
determine where a section is linked. Since these symbols are external, they appear in the 
link map. Each symbol can be accessed in any assembly language module if it is declared 
with a .global directive. Values are assigned to these symbols as follows: 

.text is assigned the first address of the .text output section. 

(It marks the beginning of executable code.) 

etext is assigned the first address following the .text output section. 

(It marks the end of executable code.) 

.data is assigned the first address of the .data output section. 

(It marks the beginning of initialized data tables.) 

edata is assigned the first address following the .data output section. 

(It marks the end of initialized data tables.) 

.bss is assigned the first address of the .bss output section. 

(It marks the beginning of uninitialized data.) 
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end is assigned the first address following the .bss output section. 
(It marks the end of uninitialized data.) 
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8.14 Creating and Filling Holes 

The linker provides you with the ability to create areas within output sections that have 
nothing linked into them. These areas are called holes. In special cases, uninitialized 
sections can also be treated as holes. This section describes how the linker handles such 
holes and how you can fill holes (and uninitialized sections) with values. 

8.14.1 Initialized and Uninitialized Sections 

There are two guidelines to remember about the contents of an output section. An output 
section contains either: 

• Raw data for the entire section, or 

• No raw data. 

A section that has raw data is said to be initialized. This means that the object file contains 
the actual memory image contents of the section. When the section is loaded, this image is 
loaded into memory at the section's specified starting address. The .text and .data sections 
always have raw data if anything was assembled into them. Named sections defined with 
the .sect assembler directive also have raw data. 

By default, the .bss section and sections defined with the .usect directive have no raw data 
(they are uninitialized). They occupy space in the memory map but have no actual contents. 
Uninitialized sections typically reserve space in RAM for variables. In the object file, an 
uninitialized section has a normal section header and may have symbols defined in it; no 
memory image, however, is stored in the section. 

8.14.2 Creating Holes 

You can create a hole in an initialized output section. A hole is created when you force the 
linker to leave extra space between input sections within an output section. When such a 
hole is created, the linker must follow the first guideline (above) and supply raw data for the 
hole. 

Holes can be created only within output sections. There can also be space between output 
sections, but such spaces are not holes. 

To create a hole in an output section, you must use a special type of linker assignment 
statement within an output section definition. The assignment statement modifies the SPC 
(denoted by “. ") by adding to it, assigning a greater value to it, or aligning it on an address 
boundary. 
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The following example uses assignment statements to create holes in output sections: 

SECTIONS 

{ 

outsect: 

{ 

filel.obj(.text) 

. += lOOh; /* Create a hole with size lOOh */ 

file2.obj(.text) 

. = align(16); /* Create a hole to align the SPC */ 
files.obj(.text) 

} 

} 

The output section outsect is built as follows: 

• The .text section from file1 .obj is linked in. 

• The linker creates a 256-byte hole. 

• The .text section from file2.obj is linked in after the hole. 

• The linker creates another hole by aligning the SPC on a 16-byte boundary. 

• Finally, the .text section from fileS.obj is linked in. 

All values assigned to the “. " symbol within a section refer to the relative address within the 
section. The linker handles assignments to the “ . " symbol as if the section started at 
address 0 (even if you have specified a binding address). Consider the statement . = 
align(16) in the example. This statement effectively aligns fileS.obj .text to start on a 16-word 
boundary within outsect. If outsect is ultimately allocated to start on an address that Is not 
aligned, fileS .text will not be aligned, either. 

Expressions that decrement “. " are illegal. For example, it is invalid to use the -= operator in 
an assignment to “ . The most common operators used in assignments to “. " are += and 
align. 

If an output section contains all input sections of a certain type (such as .text), you can use 
the following statements to create a hole at the beginning or end of the output section. For 
example: 

.text: { .+= lOOh; } /* Hole at the beginning */ 

.data: { 

*(.data) 

. += lOOh; } /* Hole at the end */ 
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Another way to create a hole in an output section is to combine an uninitialized section with 
an initialized section to form a single output section. In this case, the linker treats the 
uninitialized section as a hole and supplies data for it Here is an example of creating a hole 
in this way: 

SECTIONS 

{ 

outsect: 

{ 

filel.obj(.text) 

filel.obj(.bss) /* This becomes a hole */ 

} 

} 

Because the .text section has raw data, all of outsect must also contain raw data (first 
guideline). Therefore, the uninitialized .bss section becomes a hole. 

Note that uninitialized sections become holes only when they are combined with initialized 
sections. If several uninitialized sections are linked together, the resulting output section is 
also uninitialized. 

8.14.3 Filling Holes 

Whenever there is a hole in an initialized output section, the linker must supply raw data to fill 
it. The linker fills holes with a 16-bit fill value that is replicated through memory until it fills the 
hole. The linker determines the fill value as follows: 

1) If the hole is formed by combining an uninitialized section with an initialized section, you 
can specify a fill value for the uninitialized section. Follow the section name with an = 
sign and a 16-bit constant. For example: 

SECTIONS 

{ 

outsect: 

{ 

filel.obj(.text) 

file2.obj(.bss) = OFFh /* Fill this hole */ 

} ' /* with OOFFh */ 

} 

2) You can also specify a fill value for all the holes In an output section by using the fill 
keyword. For example: 

SECTIONS 

{ 


outsect: fill = OFFOOh 

/* 

This 

fills holes */ 


{ 

. += lOh; 

/* 

with 

OFFOOh 


*/ 

/* 

This 

creates 

a hole 

*/ 

filel.obj(.text) 
filel.obj(.bss) 

/* 

This 

creates 

another hole 

*/ 


} 

} 
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3) If you do not specify an initialization value for a hole, the linker fills the hole with the value 
specified with -f. Suppose the command file link.cmd contains the following SECTIONS 
directive. For example: 

SECTIONS 

{ 

•text: { .= 100; } /* Create a 100-word hole */ 

} 

Now invoke the linker with the -f option: 

lnk430 -f OFFFFh link.cmd 

This fills the hole with OFFFFh. 

4) If you do not invoke the linker with the -f option, the linker fills holes with Os. 

Whenever a hole is created and filled in an initialized output section, the hole is identified in 
the link map along with the value the linker uses to fill it. 

8.14.4 Explicit Initialization of Uninitialized Sections 

An uninitialized section becomes a hole only when it is combined with an initialized section. 
When uninitialized sections are combined with each other, the resulting output section 
remains uninitialized and has no raw data in the output file. 

However, you can force the linker to initialize an uninitialized section by specifying an explicit 
fill value for it in the SECTIONS directive. This causes the entire section to have raw data 
(the fill value). For example: 

SECTIONS 

{ 

.bss: fill = 1234h /* Fills .bss with 1234h */ 

} 


Note: Filling Sections 

Because filling a section (even with Os) causes raw data to be generated for the entire 
section in the output file, your output file will be very large if you specify fill values for large 
sections or holes. 
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8.14.5 Examples of Using Initialized Holes 

The MSP430X201 device has 4K bytes of program memory, starting at location OFOOOh. The 
top bytes of this area are reserved for interrupt vectors. Suppose you want to link the .text 
sections from three object files into a .text output section that begins at address OFOOOh. 
Suppose also that you have a section of initialized interrupt vectors called int_vecs that you 
want to link at address OFFEOh. You could fill the space between the end of the .text section 
and the beginning of the interrupt vectors; the figure shows the space filled with a 1-byte fill 
value of OEFh and illustrates the desired memory map for program memory. 


OFOOOh 


OFFEOh 

OFFFFh 


.text 


Fill with 
OEFh 


Vectors 


Figure 8.6: Initialized Hole 


To obtain the configuration shown in the figure, you must create one large output section that 
has .text at the beginning, int_vecs at the end, and a hole between filled with OEFh: 

SECTIONS 
{ 

prog OFOOOh :fill = OEFEFh 
{ 

filel.obj(.text) 
file2.obj(.text) 
files.obj(.text) 

. = OFEOh; 
filel.obj(int_vecs) 

} 

} 

The fill value must be a 16-bit constant. To have the value OEFh in each byte, the fill value 
was specified as OEFEFh. 

Notice that the value OFEOh, which is assigned to the section program counter (.), is relative 
to the beginning of the section. Because the section begins at OFOOOh, the hole is actually 
created from the end of the .text section to address OFFEOh. 


/* Define prog and start at OFOOOh and */ 


/* Specify a fill value */ 

/* Link .text sections from each file */ 

/* Create hole to OFEOh (OFFEOh abs) */ 
/* Link in the vectors section */ 
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8.15 Partial (Incremental) Linking 

An output file that has been linked can be linked again with additional modules. This is 
known as partial linking, or incremental linking. Partial linking allows you to partition large 
applications, link each part separately, and then link all the parts together to create the final 
executable program. 

Follow these guidelines for producing a file that you will relink: 

• Intermediate files must have relocation information. Use the -r option when you link the 
file the first time. 

• Intermediate files must have symbolic information. By default, the linker retains symbolic 
information in its output. Do not use the -s option if you plan to relink a file, because -s 
strips symbolic information from the output module. 

• Intermediate link steps should be concerned only with the formation of output sections 
and not with allocation. All allocation, binding, and MEMORY directives should be 
performed in the final link step. 

The following example shows how you can use partial linking: 

Step 1: Link the file file1.com; use the -r option to retain relocation information in the output 
file tempoutl.out. 

Ink430 -r -o tempoutl filel.com 

file1.com contains: 

SECTIONS 

{ 

ssl: { 

f1.obj 
f2.obj 


fn.obj 

} 

} 
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Step 2: Link the file file2.com; use the -r option to retain relocation information in the output 
file tempout2.out. 

Ink430 -r -o tempout2 file2.com 

file2.com contains: 

SECTIONS 

{ 

ss2: { 

gl.obj 
g2.obj 


gn.obj 
} 

} 

Step 3: Link tempouti .out and tempout2.out: 

lnk430 -m final.map -o final.out tempouti.out tempout2.out 
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8.17 Linker Example 


This example links a program called demo.out. There are three object modules, demo.ob], 
ctrl.obj, and tables.obj. 

Assume the following memory configuration: 


Address Range 

200h to 2FFh 
1F00h to IFFFh 
2000h to 3FFFh 
OFOOOh to OFFFFh 


Memory Contents 

internal RAM 
Data EEPROM 
8K external RAM 
4K internal program ROM 


The program is built from the following elements: 

• Executable code, contained in the .text sections of demo.ob] and ctrl.obj, must be linked 
into program ROM. The symbol SETUP must be defined as the program entry point. 

• A set of interrupt vectors, contained in the int_vecs section of tables.obj, must be linked 
at address OFFEOh in program ROM. 

• A table of coefficients, contained in the .data section of tables.obj, must be linked into 
.EEPROM. The remainder of EEPROM must be initialized with the value 0A26Eh. 

• A set of variables, contained in the .bss section of ctrl.obj, must be linked into the RAM. 
These variables must be preinitialized to OFFFFh. 

• Another .bss section in demo.ob] must be linked into external RAM. 

The next two figures illustrate the linker command file and the map file for this example. 
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/* Specify the Linker Options 
/************************************************ 
-e SETUP /* Define the entry point 

-o demo.out /* Name the output file 

-m demo.map /* Create a load map 

/**************************************** 

/* Specify the Input Files 
/*********************************************•** 
demo.obj 
Ctrl .obj 
tables.obj 

/**************************************** 

/* Specify the Memory Configuration 
^■*-*************************************** 

MEMORY 

{ 








r -jt j 

*/ 

f * * * * j 

*/ 
*/ 
V 

t- * * * ★ j 

*/ 

<■*★*•*•! 


RAM 

EEPROM 

RAMEXT 

ROM 


origin 

origin 

origin 

origin 


0200h 

iFOOh 

2000h 

OFOOOh 


length = OlOOh 
length = OlOOh 
length = 2000h 
length = lOOOh 


} 

/***************************** 
/* Specify the Output Sections 
SECTIONS 

.text: > ROM 


k'k'k'k'k-k'k-k 


int_vecs OFFEOh: {} 

.data: 

{ 

tables.obj(.data) 
. = lOOh; 

} = 0A26Eh > EEPROM 

ctrl_vars: 

{ 

Ctrl .obj(.bss) 

} = OFFFFh > RAM 


/* Link all .text sections into ROM 
/* Link interrupts at FFEOh 
/* Link the data sections 


/* Create a hole to end of the block 
/* Fill and link into EEPROM 


/* Create new section for Ctrl vars 

/* Fill with OFFFFh and link to RAM 


} 

/ 

/ 

/ 


.bss > RAMEXT /* Link all remaining .bss sections 

************************************************************** 
End of Linker Command File 


/ 

/ 

/ 

/ 


Figure 8.7: Linker Command File, demo.cmd 


Now invoke the linker by entering the following command: 

Ink430 demo.cmd 

This creates the map file shown in the next figure and an output file called demo.out that can 
be run on the MSP430. 
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Version 1 


Thu Feb 10 09:21:32 1994 
OUTPUT FILE NAME: <demo.out> 

ENTRY POINT SYMBOL: "SETUP" addxess: 


MEMORY CONFIGURATION 

name origin 


name 

RAM 

EEPROM 

RAMEXT 


00000200 

OOOOlfOO 

00002000 


length 

000000100 

000000100 

000002000 


attributes 

RWIX 

RWIX 

RWIX 


ROM 


OOOOfOOO 

000001000 

RWIX 

SECTION 

ALLOCATION MAP 



output 




attributes/ 

section 

page 

origin 

length 

input sections 

. text 

0 

OOOOfOOO 

00000010 




OOOOfOOO 

00000008 

demo.obj (.text) 



OOOOfOOO 

00000000 

tables.obj (.text) 



OOOOfOOO 

00000008 

Ctrl.obj ( .text) 

int_vecs 

0 

OOOOffeO 

00000020 




OOOOffeO 

00000020 

tables, obj (int__vecs) 

. data 

0 

OOOOlfOO 

00000100 




OOOOlfOO 

00000008 

tables.obj (.data) 



OOOOlfOO 

000000f8 

--HOLE-- [fill = a26e 



00002000 

00000000 

Ctrl.obj (.data) 



00002000 

00000000 

demo.obj (.data) 

ctrl_var 

0 

00000200 

00000004 




00000200 

00000004 

Ctrl.obj (.bss) [fill 

. bss 

0 

00002000 

00000004 

UNINITIALIZED 



00002000 

00000004 

demo.obj (.bss) 



00002004 

00000000 

tables.obj (.bss) 


GLOBAL SYMBOLS 
address name 
00002000 .bss 
OOOOlfOO .data 
OOOOfOOO .text 
OOOOfOOO SETUP 
00002000 edata 
00002004 end 
OOOOfOlO etext 


address 

OOOOlfOO 

00002000 

00002000 

00002004 

OOOOfOOO 

OOOOfOOO 

OOOOfOlO 


name 
. data 
edata 
. bss 
end 
. text 
SETUP 
etext 


i 7 symbo1s] 


Figure 8.8: Output Map File, demo.map 
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9 Absolute Lister Description 


The MSP430 absolute lister is a debugging tool. This utility accepts linked object files as 
input and creates .abs files as output. These .abs files can be assembled to produce a listing 
that shows the absolute addresses of object code. Normally, this is a tedious process 
requiring many manual operations; the absolute lister utility, however, performs these 
operations automatically. 
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9.1 Producing an Absolute Listing 


The figure illustrates the steps required to produce an absolute listing. 



Figure 9.1: Absolute Lister Development Flow 
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9.2 Invoking the Absolute Lister 

The syntax for invoking the absolute lister is; 


abs430 filename 


where filename must be a linked object file. The absolute lister assumes that this file has an 
extension of .out. (This is the extension that the linker produces for output files). 

If you omit the filename when you invoke the absolute lister, the utility prompts you for a 
filename. 

The absolute lister produces an output file for each file that was linked to create filename.ouX. 
These files are named with the individual filenames and an extension of .abs. 

Assemble this file and use the -a assembler option to create the absolute listing: 

asm430 filename. ahs -a 
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9.3 Absolute Lister Example 


This example uses three source files. Note that modulel.asm and module2.asm both include 
the file globals.def. 


modulel.asm 

module2.asm 

globals.def 

.bss xflags,2 

.copy "globals.def 

.global flags 

.bss flags 

.text 

Gflag .set 2 

.copy "globals.def 

bic #Gflag,&flags 


.text 



bis #Gflag,&flags 




The following steps create absolute listings for the files modulel .asm and module2.asm: 

Step 1: First, assemble modulel.asm and module2.asm: 

asm430 modulel 
asm430 module2 

This creates two object files called modulel .obj and module2.obj. 

Step 2: Next, link modulel .ob] and module2.obj. using the following linker command file. 


called abstest.cmd: 

/****************************************************/ 
/* File abstest.cmd -- COFF linker control file */ 

/* for linking MSP430 modules */ 

/****************************************************/ 
-o ABSTEST.OUT /* executable output file */ 

-m ABSTEST.MAP /* output map file */ 

/* input files */ 

MODULEl.OBJ 
MODULE2.OBJ 


/* define MSP430 memory map 
MEMORY 
{ 

RAM: origin=00200h 

ROM: origin=0F000h 

} 

/* define the output sections */ 

SECTIONS 
{ 

.bss: >RAM 

.text: >ROM 

} 


*/ 


length^OlOOh 

length=1000h 
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Invoke the linker: 



Ink430 abstest.cmd 

This creates an executable object file called abstest.out; use this new file as input 
for the absolute lister. 

Step 3: Now, invoke the absolute lister: 


abs430 abstest.out 

This creates two files called modulel.abs and module2.abs: 

moduiel.abs: 

.nolist 

flags 

.setsym 

0202h 

. bss 

.setsym 

0200h 

end 

.setsym 

0203h 

. text 

. setsym 

OfOOOh 

etext 

.setsym 

OfOOSh 

. data 

.setsym 

OOh 

edata 

.setsym 

OOh 


.setsect 

".text", Of00Oh 


.setsect 

".data",OOh 


.setsect 
• list 
. text 

".bss",0200h 

module2.abs: 

. copy 

.nolist 

"MODULE1.ASM" 

flags 

.setsym 

0202h 

. bss 

.setsym 

0200h 

end 

.setsym 

0203h 

. text 

.setsym 

OfOOOh 

etext 

.setsym 

OfOOSh 

. data 

.setsym 

OOh 

edata 

. setsym 

OOh 


.setsect 

".text",Of004h 


. setsect 

".data",OOh 


.setsect 
. list 
. text 

".bss",0203h 


. copy 

"MODULE2.ASM" 
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These files have information that the assembler needs when you invoke it in step 4: 

• They contain .setsym directives, which equate values to global symbols. Both 
files contain global equates for the symbol flags. The symbol flags was defined 
in the file globals.def, which was included in modulel.asm and module2.asm. 

• They contain .setsect directives, which define the absolute addresses for 
sections. 

• They contain .copy directives, which tell the assembler which assembly 
language source file to include. 

Note that the .setsym and .setsect directives are not useful in normal assembly; they 
are useful only for creating absolute listings. 

Step 4: Finally, assemble the .abs files created by the absolute lister (remember that you 
must use the -a option when you invoke the assembler): 

asm430 -a modulel.abs 
asm430 -a module2.abs 

This creates two listing files called modulel.lst and module2.lst; no object code is 
produced. These listing files are similar to normal listing files; however, the 
addresses shown are absolute addresses. The absolute listing files created are: 

modulel.lst: 

MSP430 Macro Assembler Version 1.00 [04/94] Wed May 25 14:12:55 1994 

Copyright (c) 1994 Texas Instruments Incorporated 

MODULE1.ABS PAGE 1 



13 

fOOO 



. text 



14 




. copy 

"MODULE1.ASM 

A 

1 

0200 



.bss 

xflags,2 

A 

2 

0202 



.bss 

flags 

A 

3 




, copy 

"globals.def" 

B 

1 




.global 

flags 

B 

2 


02 

Gf lag 

. set 

2 

B 

3 






B 

4 






A 

4 

fOOO 



. text 


A 

5 

fOOO 

-d3a20202 


bis 

#Gflag, Scflags 


A 6 

No Errors, No Warnings 
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module2.lst: 

MSP430 Macro Assembler Version 1.00 [04/94] Wed May 25 14:42:20 1994 


Copyright (c) 

1994 Texas 

Instruments 

Incorporated 

MODULE2.ABS 




PAGE 


13 f004 



. text 



14 



. copy 

"MODULE2.ASM 

A 

1 



. copy 

"globals.def" 

B 

1 



.global 

flags 

B 

2 

02 

Gf lag 

. set 

2 

B 

3 





B 

4 





A 

2 f004 



. text 


A 

3 f004 

!c3a20202 


bic 

#Gflag, Scflags 

A 

4 





No 

Errors, No 

Warnings 
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10 Object Format Converter Description 


Most EPROM programmers do not accept COFF object files as input. The object format 
converter converts a COFF object file into one of four object formats that most EPROM 
programmers accept as input: 

Extended Tektronix hex object format supports 32-bit addresses. 

Intel hex object format supports 16-bit addresses. 

Motorola S format supports 16-bit addresses. 

Tl-tagged object format supports 16-bit addresses. 
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10.1 Object Format Converter Development Flow 

The figure illustrates the object format converter's role in the assembly language 
development process. 



Figure 10.1: Object Format Converter Development Flow 
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10.2 Extended Tektronix Hex Object Format 


The Extended Tektronix hex object format supports 32-bit addresses and has three types of 
records: data, symbol, and termination records. 

termination record signifies the end of a module. 

symbol record contains information about program sections. 

data record contains the header field, the load address, and the object code. 

The header field, in the data record, contains the following information; 



Number of 
ASCII 
Characters 

Description 

% 

1 

Data type is Extended Tektronix hex format 

Block length 

2 

Number of characters in the record, minus the % 

Block type 

1 

6 = data record 

8 = termination record 

Sumcheck 

2 

A 2-digit hex sum modulo 256 of all values in the 


record except the % and the sumcheck itself. 


The load address, in the data record, specifies where the object code will be located. The 
first number specifies the address length; this is always 8. The remaining characters of the 
data record contain the object code, 2 characters per byte. 


Sumcheck; 21H = 1 +5+6+8+1+0+0+0+0+0+0+0+ 

2 + 0 + 2 + 0 + 2 + 0 + 2 + 0 + 2 + 0 + 2+0 


Block Length 
15H = 21 

Header _ 
Character 




• Object Code: 6 bytes 


I I 

%15621810000000202020202020 

U U LJI___I 


• Load Address: 10000000H 


Block Type: Length of 
6 (data) Load Address 


Figure 10.2: Extended Tektronix Hex Object Format 
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10.3 Intel Hex Object Format 

The Intel hex object format supports 16-bit addresses and consists of a 9-character (4-field) 
prefix, which defines the start of record, byte count, load address, and record type, and a 2- 
character sumcheck suffix. 

The two record types, which are represented in the 9-character prefix, are described below: 
00 = data record (begins with the colon start character) 

01 = end-of-file record 

Record type 00 , the data record, begins with the colon (: ) start character and is followed by 
the byte count, the address of the first data byte, the record type (00), and the sumcheck. 
The sumcheck is the 2s complement (in binary) of the preceding bytes in the record, 
including byte count, address, and data bytes. 

Record type 01 , the end-of-file record, also begins with the colon ( : ) start character. The 
colon is followed by the byte count, the address, the record type (01), and the sumcheck. 


Start 

Character 


Address 

: lOOOOOOOFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFOQ- 
: lOOOlOOOFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFO 
: 1000200OFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEO 
: 10003 OOOFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFDO 
: 100 04 0 0 0FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFC0_ 
rOOOOOOOlFF M 


Byte __It' 

Count Record 

Type 



Sumcheck 


Data 

Records 


Figure 10.3: Intel Hex Object Format 
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10.4 Tl-Tagged Object Format 

The Tl-tagged object format supports 16-bit addresses and consists of a start-of-file 
record, data records, and end-of-file record. Each of the data records is made up of a series 
of small fields and is signified by a tag character. The following is a list of the significant tag 
characters: 

K is followed by the program Identifier. 

7 is followed by a sumcheck (acknowledged). 

8 is followed by a sumcheck (ignored). 

9 is followed by a load address. 

B is followed by a data word (4 characters). 

F identifies the end of the data record. 


Program 

Identifier 




1 


n 


• Tag Characters 


n 


n 


n 


KOOOOCOFTFOTI 

900000BFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFF7F234F 
9 00 020BFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFF7F4 OOF 
900040BFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFF7F3FFF 
9 0 0 0 5 0BFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFF7F3 FDF . 


V 


Load 

Address 


End of File 
Record 


W 

Data 
Words 


Sumcheck 


Data 

Records 


Figure 10.4: Tl-Tagged Object Format 


If any data fields appear before the first address, the first field is assigned address 0000. 
Address fields may be expressed for any data byte, but none is required. The sumcheck 
field, which is preceded by the tag character 7, is a 2s complement of the sum of the 8-bit 
ASCII values of characters, beginning with the first tag character and ending with the 
sumcheck tag character (7 or 8). The end-of-file record is a (:) colon. 
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10.5 Motorola S Format 

The Motorola S format supports 16-bit addresses and consists of a start-of -file record, data 
records, and an end-of-file record. Each record Is made up of five fields: record type, byte 
count, address, data, and sumcheck. The three record types are as follows: 

• SO Header record 

• SI Code/data record 

• S9 Termination record 

The byte count is the character pair count in the record, excluding the type and byte count 
itself. 

The sumcheck is the least significant byte of the ones complement of the sum of the values 
represented by the pairs of characters making up the byte count, address, and the code/data 
fields. 


Address 


“7. T-n 


S00600004844521B 

S1137000D514D515D51D65178E700D07FB7001173D 
S10B70100703700115F9FFFFED *-“7 
S9030000FC 


Sumcheck 


Header 
□ Record 

“I Data 
J Records 

^ Termination 
Record 


Figure 10.5: Motorola S Format 
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10.6 Invoking the Object Format Converter 

To invoke the object format converter, enter 

rom430 [-option] [COFF input file [output file] ] 


rom430 is the command that invokes the object format converter; all parameters are 
optional. 

options can be entered anywhere on the line, but the order of filenames is significant. The 
filenames (if used) are interpreted as: 

1) The input filename. 

2) The output filename. 

• These are the options: 

-X specifies Tektronix hex object format for the output. 

-i specifies Intel hex object format for the output. 

-t specifies Tl-tagged object format for the output. 

-m specifies Motorola S format for the output. 

If you don't specify an option, the object format converter produces Tektronix hex format 
output files. 

• If you do not specify an input filename, the object format converter prompts for it. If you 
specify a filename without an extension, the utility assumes that the filename has a 
default extension of .obj. 

• If you do not specify a second filename, the object format converter uses the input 
filename with an extension based on the format chosen: 


Option 

Format 

Extension 

-X 

Tektronics 

.tek 

-i 

Intel Hex 

.int 

-t 

Tl-Tagged 

tag 

-m 

Motorola S 

.ms 


When the utility finishes converting the input file, it prints the message Translation complete. 
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10.7 Object Format Converter Examples 

Here are some examples of using the object format converter. 

• Example 1 

You can invoke the object format converter with no options and no filenames by entering: 

rom430 

The utility will print the following banner and prompt: 

COFF Object Converter Version 1.00 

Copyright (c) 1994, Texas Instruments Incorporated 
Coff file [.obj] : 

If, for example, you respond to the prompt with a filename of test, the object format 
converter uses the file test.obj as an input file. The utility produces an output file named 
test.tek in Tektronix hex format. (Tektronix format is the default when you don't specify a 
format.) 

• Example 2 

If you enter 

rom430 -i in outl 

the utility uses in.obj as the input file. It creates an Intel hex format file named out1 .in. 

• Example 3 
If you enter 

rom430 -x in.tmp out.x 

the object format converter uses in.tmp as the input file. It produces Tektronix hex format 
output file named out.x. 

• Example 4 

If you enter: 

rom430 -t test 

the object format converter uses test.obj as the input file. It produces an output file 
named test.tag in Tl-tagged format. 
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10.8 Halt Conditions 

Two situations cause the object format converter to abort execution: 

1) If any of the specified files cannot be opened, the object format converter prints the 
message Input COFF file cannot be opened and aborts. 

2) If you supply the utility with the name of an invalid object file, the object format converter 
prints the message Corrupt input file and aborts. 
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20 Common Object File Format 

The MSP430 assembler and linker create object files that are in common object file format 
(COFF). COFF is an implementation of an object file format of the same name that was 
developed by AT&T for use on UNIX-based systems. This object file format is used because 
it encourages modular programming and provides more powerful and flexible methods for 
managing code segments and target system memory. 

One of the basic COFF concepts is sections. If you understand section operation, you will be 
able to use the assembly language tools more efficiently. 

This appendix contains technical details about COFF object file structure. Much of this 
information pertains to the symbolic debugging information that is produced by high level 
programming languages. The main purpose of this appendix is to provide supplementary 
information for those of you who are interested in the internal format of COFF object files. 
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20.1 How the COFF File Is Structured 

The elements of a COFF object file describe the file's sections and symbolic debugging 
information. These elements include: 

• a file header. 

• optional header information. 

• a table of section headers. 

• raw data for each initialized section. 

• relocation information for each initialized section. 

• line number entries for each initialized section. 

• a symbol table. 

• a string table. 

The assembler and linker produce object files with the same COFF structure; however, a 
program that is linked for the final time does not usually contain relocation entries. 


file header 
optional file header 
section 1 header 


section n header 

section 1 
_ra w data _ 


section n 

_ raw data _ 

section 1 

relocati on i n for mation 
section n 

relocation information 
section 1 
line numbers 


section n 
line numbers 
symbol table 

string table 


N 


< 


< 


< 


/ 


section headers 


raw data 
(executable code 
and initialized data) 


relocation 

information 


line number 
entries 


Figure 20.1: COFF File Structure 
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The following figure shows a typical example of a COFF object file that contains the three 
default sections, .text, .data, and .bss, and a named section (referred to as <named>). 
Although uninitialized sections have section headers, they have no raw data, relocation 
information, or line number entries. This is because the .bss and .usect directives simply 
reserve space for uninitialized data; uninitialized sections contain no actual code. 



Figure 20.2: Sample COFF Object File 
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20.2 How the File Header Is Structured 

The file header contains 20 bytes of information that describe the general format of an object 
file. 


Byte 

Number 

Type 

Description 

0-1 

Unsigned short integer 

Magic number, indicates that the file can be 
executed in a MSP430 system. 

2-3 

Unsigned short integer 

Number of section headers. 

4-7 

Long integer 

Time and date stamp, indicates when the file 
was created. 

8-11 

Long integer 

File pointer, contains the symbol table's starting 
address. 

12-15 

Long integer 

Number of entries in the symbol table. 

16-17 

Unsigned short integer 

Number of bytes in the optional header. This 
field is either 0 or 28; if it is 0, there is no 
optional file header. 

18-19 

Unsigned short integer 

Flags (see Table A-2). 


Table 20.1 : File Header Contents 

The following table lists the flags that can appear in bytes 18 and 19 of the file header. Any 
number and combination of these flags can be set at the same time (for example, if bytes 18 
and 19 are set to 0003h, F_RELFLG and F_EXEC are both set.) 


Mnemonic 

Flag 

Description 

F_RELFLG 

0001 h 

Relocation information was stripped from the file. 

F_EXEC 

0002h 

The file is relocatable (it contains no unresolved external 
references). 

F_LNNO 

0004h 

Line numbers were stripped from the file. 

F_LSYMS 

0008h 

Local symbols were stripped from the file. 

F_BENDIAN 

0200h 

The file has the byte ordering used by MSP430 devices (most 
significant byte first). 


Table 20.2: File Header Flags (Bytes 18 and 19) 
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20.3 Optional File Header Format 


The linker creates the optional file header and uses it to perform relocation at download time. 
Partially linked files do not contain optional file headers. 


Byte 

Number 

Type 

Description 

0-1 

Short integer 

Magic number 

2-3 

Short integer 

Version stamp 

4-7 

Long integer 

Size (in bytes) of executable code 

8-11 

Long integer 

Size (in bytes) of initialized data 

12-15 

Long integer 

Size (in bytes) of uninitialized data 

16-19 

Long integer 

Entry point 

20-23 

Long integer 

Beginning address of executable code 

24-27 

Long integer 

Beginning address of initialized data 


Table 20.3: Optional File Header Contents 
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20.4 How Section Headers Are Structured 

COFF object files contain a table of section headers that define where each section begins in 
the object file. Each section has its own section header. 


Byte 

Number 

Type 

Description 

0-7 

Character 

Eight-character section name, padded with nulls 

8-11 

Long integer 

Section's physical address 

12-15 

Long integer 

Section's virtual address 

16-19 

Long integer 

Section size In words 

20-23 

Long integer 

File pointer to raw data 

24-27 

Long integer 

File pointer to relocation entries 

28-31 

Long integer 

File pointer to line number entries 

32-33 

Unsigned short integer 

Number of relocation enitnies 

34-35 

Unsigned short integer 

Number of line number entries 

36-37 

Unsigned short integer 

Flags (see Table A-5) 

38 

Character 

Reserved 

39 

Unsigned Character 

Memory page number 


Table 20.4: Section Header Contents 


Mnemonic 

Flag 

Description 

STYP_REG 

OOOOh 

Regular section (allocated, relocated, loaded) 

STYP_DSECT 

0001 h 

Dummy section (relocated, not allocated, not loaded) 

STYP_NOLOAD 

0002h 

Noload section (allocated, relocated, not loaded) 

STYP_GROUP 

0004h 

Grouped section (formed from several input sections) 

STYP_PAD 

0008h 

Padding section (loaded, not allocated, not relocated) 

STYP.COPY 

001 Oh 

Copy section (relocated, loaded, but not allocated; relocation 
and line number entries are processed normally) 

STYP_TEXT 

0020h 

Section contains executable code 

STYP_DATA 

0040h 

Section contains Initialized data 

STYP_BSS 

0080h 

Section contains uninitialized data 


Note: The term loaded means that the raw data for this section appears in the object file. 
Table 20.5: Section Header Flags (Bytes 36 and 37) 
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The flags listed in the last table can be combined; for example, if the flag's word is set to 
024h, both STYP_GROUP and STYP_TEXT are set. 

The example illustrates how the pointers in a section header would point to the various 
elements in an object file that are associated with the .text section. 


.text 

Section 

Header 


0-7 8-11 12-15 16-19 20-23 24-27 28-31 32-33 34-35 36-37 38 39 


.text 




.text 

raw data 


text 

relocation informatron 


.text 


Example 20.1 : Section Header Pointers for the .text Section 

As Figure A-2 , page A-3, shows, uninitialized sections (created with the .bss and .usect 
directives) vary from this format. Although uninitialized sections have section headers, they 
have no raw data, no relocation information, and no line number information; also, they 
occupy no actual space in the object file. Therefore, the number of relocation entries, the 
number of line number entries, and the file pointers are 0 for an uninitialized section. The 
header of an uninitialized section simply tells the linker how much space for variables it 
should reserve in the memory map. 
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20.5 Structuring Relocation Information 

A COFF object file has one relocation entry for each relocatable reference. The assembler 
automatically generates relocation entries. The linker reads the relocation entries as it reads 
each input section and performs relocation. The relocation entries determine how references 
within each input section are treated. 

The relocation information entries use the 10-byte format shown in the table. 


Byte 

Number 

Type 

Description 

0-3 

Long integer 

Virtual address of the reference 

4-5 

Unsigned short integer 

Symbol table index (0-65535) 

6-7 

Unsigned short integer 

Reserved 

8-9 

Unsigned short integer 

Relocation type (see Table A-7) 


Table 20.6: Relocation Entry Contents 

• The virtual address is the symbol's address in the current section before relocation; it 
specifies where a relocation must occur. (This is the address of the field in the object 
code that must be patched.) 

Here's an example of code that generates a relocation entry: 

2 .global X 

3 0000 140300000 br #X 

In this example, the virtual address of the relocatable field is 0001. 

• The symbol table index is the index of the referenced symbol. In the preceding 
example, this field would contain the index of X in the symbol table. The amount of the 
relocation is the difference between the symbol's current address in the section and its 
assembly-time address. The relocatable field must be relocated by the same amount as 
the referenced symbol. In the example, X has a value of 0 before relocation. Suppose X 
is relocated to address 2000h. This is the relocation amount (2000h - 0 = 2000h), so the 
relocation field at address 1 is patched by adding 2000h to it. 

You can determine a symbol's relocated address if you know which section it is defined 
in. For example, if X is defined in .data and .data is relocated by 2000h, X is relocated by 
2000h. 

If the symbol table index in a relocation entry is -1 (OFFFFh), this is called an internal 
relocation. In this case, the relocation amount is simply the amount by which the current 
section is being relocated. 
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• The relocation type specifies the size of the field to be patched and describes how the 
patched value should be calculated. The type field depends on the addressing mode that 
was used to generate the relocatable reference. In the preceding example, the actual 
address of the referenced symbol (X) will be placed in a 16-bit field in the object code. 
This is a 16-bit direct relocation, so the relocation type is R_RELWORD. 


Mnemonic 

Flag 

Relocation Type 

R_ABS 

OOOOh 

No relocation 

R_RELBYTE 

OOOFh 

8-bit direct reference to symbol's address 

R_RELWORD 

OOlOh 

16-bit direct reference to symbol's address 

R_HIWORD 

0031 h 

8-bit reference to MSB of word 


Table 20.7: Relocation Types (Bytes 8 and 9) 
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20.6 How the Line Number Table Is Structured 

The object file contains a table of line number entries that are useful for symbolic debugging. 
When the C compiler produces several lines of assembly language code, it creates a line- 
number entry that maps these lines back to the original line of C source code that generated 
them. Each single line number entry contains 6 bytes of information. 


Byte 

Number 

Type 

Description 

0-3 

Long integer 

This entry may have one of two values: 

1) lf it is the first entry in a block of line-number entries, it 
points to a symbol entry in the symbol table. 

2) If it is not the first entry in a block, it is the physical address 
of the line indicated by bytes 4-5. 

4-5 

Unsigned 
short integer 

This entry may have one of two values: 

1) If this field is 0, this is the first line of a function entry. 

2) If this field is not 0, this is the line number of a line of C 
source code. 


Table 20.8: Line Number Entry Format 

The figure shows how line number entries are grouped into blocks. 


Symbol Index 1 

physical address 
physical address 

0 

line number 

line number 



Symbol Indexn 

physical address 
physical address 

0 

line number 

line number 


Figure 20.3: Line Number Blocks 

As the figure shows, each entry is divided into halves: 

• For the first line of a function, 

• Bytes 0-3 point to the name of a symbol or a function in the symbol table. 

• Bytes 4-5 contain a 0, which indicates the beginning of a block. 
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• For the remaining lines in a function, 

• Bytes 0-3 show the physical address (the number of bytes created by a line of C 
source). 

. Bytes 4-5 show the address of the original C source, relative to its appearance in the 
C source program. 

The line entry table can contain many of these blocks. 

The following example illustrates the line number entries for a function named XYZ. As 
shown, the function name is entered as a symbol in the symbol table. The first portion on 
XYZ's block of line number entries points to the function name in the symbol table. Assume 
that the original function in the C source contained three lines of code. The first line of code 
produces 4 bytes of assembly language code, the second line produces 3 bytes, and the 
third line produces 10 bytes. 





< 


line number 
entries 


symbol table 


Example 20.2: Line Number Entries 

(Note that the symbol table entry for XYZ has a field that points back to the beginning of the 
line number block.) 

Because line numbers are not often needed, the linker provides an option (-s) that strips line 
number information from the object file; this provides a more compact object module. 
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20.7 Symbol Table Structure and Content 

The order of symbols in the symbol table is very important. 



function 1 


function 2 | 



filename 1 

function 1 

local symbols 
for function 1 


' static variables 


defined global symbols 

undefined global symbols 


Figure 20.4: Symbol Table Contents 

Static variables refer to symbols defined in C that have storage class static outside any 
function. If you have several modules that use symbols with the same name, making them 
static confines the scope of each symbol to the module that defines it (this eliminates 
multiple-definition conflicts). 

The entry for each symbol in the symbol table contains the symbol's: 

• Name (or an offset into the string table). 

• Type. 

• Value. 

• Section it was defined in. 

• Storage class. 

• Basic type (integer, character, etc.). 
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• Derived type (array, structure, etc.). 

• Dimensions. 

• Line number of the source code that defined the symbol. 

Section names are also defined in the symbol table. 

All symbol entries, regardless of the symbol's class and type, have the same format in the 
symbol table. Each symbol table entry contains the 18 bytes of information listed in the next 
table. Each symbol may also have an 18-byte auxiliary entry; the special symbols listed in 
the table after next always have an auxiliary entry. Some symbols may not have all the 
characteristics listed above; if a particular field is not set, it is set to null. 


Byte 

Number 

Type 

Description 

0-7 

Character 

This field contains one of the following: 

1) An 8-character symbol name, padded with nulls 

2) An offset into the string table if the symbol name is 
longer than 8 characters 

8-11 

Long integer 

Symbol value; storage class dependent 

12-13 

Short integer 

Section number of the symbol 

14-15 

Unsigned short 
integer 

Basic and derived type specification 

16 

Character 

Storage class of the symbol 

17 

Character 

Number of auxiliary entries (always 0 or 1) 


Table 20.9: Symbol Table Entry Contents 
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20.7.1 Special Symbols Used in the Symbol Table 

The symbol table contains some special symbols that are generated by the compiler, 
assembler, and linker. Each special symbol contains ordinary symbol table information and 
an auxiliary entry. 


Symbol 

Description 

.file 

File name 

.text 

Address of the .text section 

.data 

Address of the .data section 

.bss 

Address of the .bss section 

.bb 

Address of the beginning of a block 

.eb 

Address of the end of a block 

.bf 

Address of the beginning of a function 

.ef 

Address of the end of a function 

.target 

Pointer to a structure or union that is returned by a function 

.nfake 

Dummy tag name for a structure, union, or enumeration 

.eos 

End of a structure, union, or enumeration 

etext 

Next available address after the end of the .text output section 

edata 

Next available address after the end of the .data output section 

end 

Next available address after the end of the .bss output section 


Table 20.10: Special Symbols in the Symbol Table 

Several of these symbols appear in pairs: 

• .eb indicate the beginning and end of a block. 

• .bf/.ef indicate the beginning and end of a function. 

• nfake/.eos name and define the limits of structures, unions, and enumerations that were 
not named. The .eos symbol is also paired with named structures, unions, and 
enumerations. 

When a structure, union, or enumeration has no tag name, the compiler assigns it a name so 
that it can be entered into the symbol table. These names are of the form /Tfake, where n is 
an integer. The compiler begins numbering these symbol names at 0. 

Symbols and Blocks - 

In C, a block is a compound statement that begins and ends with braces. A block always 
contains symbols. The symbol definitions for any particular block are grouped together in the 


A-16 




MSP430 Family 


Common Object File Format 


symbol table and are delineated by the .bb/.eb special symbols. Note that blocks can be 
nested in C, and their symbol table entries can also be nested correspondingly. The following 
figure shows how block symbols are grouped in the symbol table. 



Symbol Table 


Block 1: 

.bb 

symbols for 
block 1 

.eb 


Block 2: 

;V::y:-V-"-bb -z 

symbol$for 
block 2 



Figure 20.5: Symbols for Blocks 


Symbols and Functions- 

The symbol definitions for a function appear in the symbol table as a group, delineated by 
.bf/.ef special symbols. The symbol table entry for the function name precedes the .bf special 
symbol. The next figure shows the format of symbol table entries for a function. 


function name 
^bf 

symbols for 
the function 

.ef 


Figure 20.6: Symbols for Functions 

if a function returns a structure or union, a symbol table entry for the special symbol .target 
will appear between the entries for the function name and the .bf special symbol. 

20.7.2 Symbol Name Format 

The first 8 bytes of a symbol table entry (bytes 0-7) indicate a symbol's name: 
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• If the symbol name is 8 characters or less, this field has type character. The name is 
padded with nulls (if necessary) and stored in bytes 0-7. 

• If the symbol name is greater than 8 characters, this field is treated as two long integers. 
The entire symbol name is stored in the string table. Bytes 0-3 contain 0, and bytes 4-7 
are an offset into the string table. 

20.7.3 String Table Structure 

Symbol names that are longer than eight characters are stored in the string table. The field in 
the symbol table entry that would normally contain the symbol's name contains, instead, a 
pointer to the symbol's name in the string table. Names are stored contiguously in the string 
table, delimited by a null byte. The first four bytes of the string table contain the size of the 
string table in bytes; thus, offsets into the string table are greater than or equal to four. 

The next figure shows an example of a string table that contains two symbol names, 
Adaptive-Filter and Fourier-Transform. The index in the string table is 4 for Adaptive-Filter 
and 20 for Fourier-Transform. 


38 

‘A’ 

CL 



‘t’ 

T 

‘v’ 



‘F’ 

D 


‘t’ 

‘e’ 



‘F’ 

‘o’ 

‘u’ 


r 

‘e’ 

mi 



a 

MM 



‘f 



‘m’ 

‘\0’ 



Figure 20.7: Sample String Table 
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20.7.4 storage Classes 

Byte 16 of the symbol table entry indicates the storage class of the symbol. Storage classes 
refer to the method in which the C compiler accesses a symbol. 


Mnemonic 

Value 

Storage Class 

Mnemonic 

Vaiue Storage Class 

C_NULL 

0 

No storage class 

C_USTATIC 

14 

Undefined static 

C_AUTO 

1 

Automatic variable 

C_ENTAG 

15 

Enumeration tag 

C_EXT 

2 

External definition 

C_MOE 

16 

Member of an 
enumeration 

C_STAT 

3 

Static 

C_REGPAR 

M 

17 

Register parameter 

C__REG 

4 

Register variable 

C_FIELD 

18 

Bit field 

C_EXTREF 

5 

External reference 

C_UEXT 

19 

Tentative external 
definition 

C_LABEL 

6 

Label 

C_STATLAB 

20 

Static load time label 

C_ULABEL 

7 

Undefined label 

C_EXTLAB 

21 

External load time 
label 

C_MOS 

8 

Member of a 

structure 

C_BLOCK 

100 

Beginning or end of 
a block; used only 
for the .bb and .eb 
special symbols 

C_ARG 

9 

Function argument 

C_FCN 

101 

Beginning or end of 
a function; used only 
for the .bf and .ef 
special symbols 

C_STRTAG 

10 

Structure tag 

C_EOS 

102 

End of structure; 
used only for the 
.eos special symbol 

C_MOU 

11 

Member of a union 

C_FILE 

103 

Filename; used only 
for the .file special 
symbol 

C_UNTAG 

12 

Union tag 

C_LINE 

104 

Used only by utility 
programs 

C_TPDEF 

13 

Type definition 



Table 20.11: Symbol Storage Classes 
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Some special symbols are restricted to certain storage classes. 


Special Restricted to This 

Symbol Storage Class 

Special Restricted to This 

Symbol Storage Class 

.file C_FILE 

.eos C_EOS 

.bb C.BLOCK 

.text C_STAT 

.eb C_BLOCK 

.data C_STAT 

.bf C_FCN 

.bss C_STAT 

.ef C_FCN 



Table 20.12: Special Symbols and Their Storage Classes 


20.7.5 Symbol Values 

Bytes 8-11 of a symbol table entry indicate a symbol's value. A symbol's value depends on 
the symbol's storage class; the table summarizes the storage classes and related values. 


Storage Class 

Value Description 

Storage Class 

Value Description 

C_AUTO 

Stack offset in bits 

C_UNTAG 

0 

C_EXT 

Relocatable address 

C_TPDEF 

0 

C_STAT 

Relocatable address 

C_ENTAG 

0 

C_REG 

Register number 

C_MOE 

Enumeration value 

C_LABEL 

Relocatable address 

C_REGPARM 

Register number 

C_MOS 

Offset in bits 

C_FIELD 

Bit displacement 

C_ARG 

Stack offset in bits 

C_BLOCK 

Relocatable address 

C_STRTAG 

0 

C_FCN 

Relocatable address 

C_MOU 

Offset in bits 

C_FILE 

0 


Table 20.13: Symbol Values and Storage Classes 

If a symbol's storage class is C_FILE, the symbol's value is a pointer to the next .file symbol. 
Thus, the .file symbols form a one-way linked list in the symbol table. When there are no 
more .file symbols, the final .file symbol points back to the first .file symbol in the symbol 
table. 

The value of a relocatable symbol is its virtual address. When the linker relocates a section, 
the value of a relocatable symbol changes accordingly. 
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20.7.6 Section Number 

Bytes 12-13 of a symbol table entry contain a number that indicates which section the 
symbol was defined in. The table lists these numbers and the sections they indicate. 


Mnemonic 

Section 

Number 

Description 

N_DEBUG 

-2 

Special symbolic debugging symbol 

N_ABS 

-1 

Absolute symbol 

N_UNDEF 

0 

Undefined external symbol 

N_SCNUM 

1 

■text section (typical) 

N_SCNUM 

2 

.data section (typical) 

N_SCNUM 

3 

■bss section (typical) 

N_SCNUM 

1-32, 767 

Section number of a named section, in the order in which 
the named sections are encountered 


Table 20.14: Section Numbers 

Note that if there were no .text, .data, or .bss sections, the numbering of named sections 
would begin with 1. 

If a symbol has a section number of 0, -1, or -2, it is not defined in a section. A section 
number of -2 indicates a symbolic debugging symbol, which includes structure, union, and 
enumeration tag names, type definitions, and the filename. A section number of -1 indicates 
that the symbol has a value but is not relocatable. A section number of 0 indicates a 
relocatable external symbol that is not defined in the current file. 

20.7.7 Type Entry 

Bytes 14-15 of the symbol table entry define the symbol's type. Each symbol has one basic 
type and one to six derived types. 

Here is the format for this 16-bit type entry: 


Derived 

Derived 

Derived 

Derived 

Derived 

Derived 

Basic 

Type 

Type 

Type 

Type 

Type 

Type 

Type 

6 

5 

4 

3 

2 

1 


2 

2 

2 

2 

2 

2 

4 


Bits 0-3 of the type field indicate the basic type. 
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Bits 4-15 of the type field are arranged as six 2-bit fields that can indicate 1 to 6 derived 
types. 


Mnemonic 

Value 

Type 

Mnemonic 

Value 

Type 

T_VOID 

0 

Void type 

T.STRUCT 

8 

Structure 

T_SCHAR1 

1 

Character 
(explicitly signed) 

T_UNION 

9 

Union 

T_CHAR 

2 

Character 
(implicitly signed) 

T_ENUM 

10 

Enumeration 

T_SHORT 

3 

Short integer 

T_LDOUBL 

E 

11 

Long Double Floating 
Point 

T_INT 

4 

Integer 

T_UCHAR 

12 

Unsigned character 

T_LONG 

5 

Long integer 

T_USHORT 

13 

Unsigned short 
integer 

T_FLOAT 

6 

Floating point 

T_UINT 

14 

Unsigned integer 

T_DOUBLE 

7 

Double floating point 

T_ULONG 

15 

Unsigned long integer 


Table 20.15: Basic Types 


Mnemonic 

Value 

Type 

Mnemonic 

Value 

Type 

DT_NON 

0 

No derived type 

DT_FCN 

2 

Function 

DT_PTR 

1 

Pointer 

DT_ARY 

3 

Array 


Table 20.16: Derived Types 

An example of a symbol with several derived types would be a symbol with a type entry of 
00000000110100112- This entry indicates that the symbol is an array of pointers to short 
integers. 

20.7.8 Auxiliary Entries 

Each symbol table entry may have one or no auxiliary entry. An auxiliary symbol table entry 
contains the same number of bytes as a symbol table entry (18), but the format of an 
auxiliary entry depends on the symbol's type and storage class. The following table 
summarizes these relationships. 


A-22 






MSP430 Family 


Common Object Fife Format 


Type Entry 


Name Storage 

Class 

Derived 
Type 1 

Basic 

Type 

Auxiliary Entry Format 

.file C_FILE 

DT_NON 

T_VOID 

Filename (see further 
tables) 

.text, .data, .bss C_STAT 

DT_NON 

T_VOID 

Section (see further 
tables) 

tagname C_STRTAG 

C_UNTAG 
C_ENTAG 

DT_NON 

T_STRUCT 

T_UNION 

T_ENUM 

Tag name (see further 
tables) 

.eos C_EOS 

DT_NON 

T_VOID 

End of structure (see 
further tables) 

fcname C_EXT 

C_STAT 

DT_FCN 

(Any) 

Function (see further 
tables) 

arrname (See note 2) 

DT_ARY 

(See note 1) 

Array (see further tables) 

.bb, .eb C_BLOCK 

DT_NON 

T_VOID 

Beginning and end of a 
block (see further tables) 

.bf, .ef C_FCN 

DT_NON 

T_VOID 

Beginning and end of a 
function (see further 
tables) 

Name related to (See note 2) 
a structure, 

union, or 

enumeration 

DT_PTR 

DT_ARR 

DT_NON 

T_STRUCT 

T_UNION 

T_ENUM 

Name related to a 
structure, union, or 
enumeration (see further 
tables) 


Notes: 1) Any except T_VOID 

2) C_AUTO, C_STAT, C_MOS, C_MOU, C_TPDEF, C_EXT 
Table 20.17: Auxiliary Symbol Table Entries Format 

In this table, tagname refers to any symbol name (including the special symbol ATfake). 
Fcname and arrname refer to any symbol name. 

A symbol that satisfies more than one condition should have a union format in its auxiliary 
entry. A symbol that satisfies none of these conditions should not have an auxiliary entry. 
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Filenames- 

Each of the auxiliary table entries for a filename contains a 14-character file name in bytes 
0-13. Bytes 14-17 are unused. 


Byte Number 

Type 

Description 

0-13 

Character 

File name 

14-17 

— 

Unused 


Table 20.18: Filename Format for Auxiliary Table Entries 


Sections 


Byte Number 

Type 

Description 

0-3 

Long integer 

Section length 

4-6 

Unsigned short integer 

Number of relocation entries 

7-8 

Unsigned short integer 

Number of line number entries 

9-17 

— 

Not used (zero filled) 


Table 20.19: Section Format for Auxiliary Table Entries 


Tag Names 


Byte Number 

Type 

Description 

0-3 

— 

Unused (zero filled) 

4-7 

Unsigned long integer 

Size of structure, union, or enumeration 

8-11 

— 

Unused (zero filled) 

12-15 

Long integer 

Index of next entry beyond this structure, 
union, or enumeration 

16-17 

— 

Unused (zero filled) 


Table 20.20: Tag Name Format for Auxiliary Table Entries 
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End of Structure 


Byte Number 

Type 

Description 

0-3 

Long integer 

Tag index 

4-7 

Unsigned long integer 

Size of structure, union, or enumeration 

8-17 

— 

Unused (zero filled) 


Table 20.21 : End-of-Structure Format for Auxiliary Table Entries 


Functions 


Byte Number 

Type 

Description 

0-3 

Long integer 

Tag index 

4-7 

Long integer 

Size of function (in bits) 

8-11 

Long integer 

File pointer to line number 

12-15 

Long integer 

Index of next entry beyond this function 

16-17 

— 

Unused (zero filled) 


Table 20.22: Function Format for Auxiliary Table Entries 


Arrays 


Byte Number 

Type 

Description 

0-3 

Long integer 

Tag index 

4-7 

Unsigned long integer 

Size of array 

8-9 

Unsigned short integer 

First dimension 

10-11 

Unsigned short integer 

Second dimension 

12-13 

Unsigned short integer 

Third dimension 

14-15 

Unsigned short integer 

Fourth dimension 

16-17 

— 

Unused (zero filled) 


Table 20.23: Array Format for Auxiliary Table Entries 
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End of Blocks and Functions 


Byte Number 

Type 

Description 

0-3 

— 

Unused (zero filled) 

4-5 

Unsigned short integer 

C source line number 

6-17 

— 

Unused (zero filled) 


Table 20.24: End-of-Blocks/Functions Format for Auxiliary Table Entries 


Beginning of Blocks and Functions 


Byte Number 

Type 

Description 

0-3 

Unsigned long integer 

Register save mask 

4-5 

Unsigned short integer 

C source line number of block begin 

6-7 

Unsigned short integer 

Number line entries for function 

8-11 

Unsigned long integer 

Size of local frame for function 

12-15 

Long integer 

Index of next entry past this block 

16-17 

— 

Unused (zero filled) 


Table 20.25: Beginning-of-Blocks/Functions Format for Auxiliary Table 


Names Related to Structures, Unions, and Enumerations 


Byte Number 

Type 

Description 

0-3 

Long integer 

Tag index 

4-7 

Unsigned long integer 

Size of the structure, union, or enumeration 

8-17 

— 

Unused (zero filled) 


Table 20.26: Structure, Union, and Enumeration Names Format for Auxiliary Table Entries 
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21 Symbolic Debugging Directives 


The MSP430 fixed-point assembler supports several directives that a high level programm¬ 
ing language can use for symbolic debugging: 

• The .sym directive defines a global variable, a local variable, or a function. Several 
parameters allow you to associate various debugging information with the symbol or 
function. 

• The .stag, .etag, and .utag directives define structures, enumerations, and unions, 
respectively. The .member directive specifies a member of a structure, enumeration, or 
union. The .eos directive ends a structure, enumeration, or union definition. 

• The .func and .endfunc directives specify the beginning and ending lines of a function. 

• The .block and .endbiock directives specify the bounds of blocks. 

• The .file directive defines a symbol in the symbol table that identifies the current source 
file name. 

• The .line directive identifies the line number of a source statement. 

These symbolic debugging directives are not usually listed in the assembly language file that 
the compiler creates. If you want them to be listed, invoke the compiler shell with the -g 
option, as shown below: 

cl430 -g input file 

This appendix contains an alphabetical directory of the symbolic debugging directives. Each 
directive contains an example of C source and the resulting assembly language code. 
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Syntax 

Description 

Exampie 


.block [ beginning line number] 

.endblock [ending line number] 

The .block and .endblock directives specify the beginning and end of a 
block. The line numbers are optional; they specify the location in the 
source file where the block is defined. Line numbers are relative to the 
beginning of the current function. 

Note that block definitions can be nested. The assembler will detect 
improper block nesting. 

Here is an example of C source that defines a block and of the 
resulting assembly language code. 

C source: 


{ 

int a,b; 
a = b; 

} 


/* Beginning of a block */ 

/* End of a block */ 


Resulting assembly language code: 

•block 4 
.sym _a,1,4,1,8 

• sym _b,2,4,1,8 

•line 5 

MOV 2(SP), 1(SP) 

.endblock 6 
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Syntax 

Description 


Example 


.file filename 

The .file directive allows a debugger to map locations in memory back 
to lines in a source file. The filename is the name of the file that 
contains the original C source program. The first 14 characters of the 
filename are significant; any pathname information is stripped away. 

You can use the .file directive in assembly code to provide a name in 
the file and improve program readability. 

Here's an example of the .file directive. The file named text.c contained 
the C source that produced this directive. 

.file "text.c" 
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Syntax 


Description 


Example 


.func [beginning line numbei] 

.endfunc [ending line number] [ , register save mask1 ] 
[, register save mask2 ] [, frame size ] 

The .func and .endfunc directives specify the beginning and end of a 
function. The line numbers are optional; they specify the location in the 
source file where the function is defined. The register save masks 
indicate which registers were saved by this function. If bit 0 of mask2 is 
1, RO was saved by the function; if bit 1 of mask2 is 1, R1 was saved; 
if bit 0 of mask1 is 1, R16 was saved; etc. The frame size parameter 
indicates how many bytes were reserved for the local frame of this 
function. 

Note that function definitions cannot be nested. 

Here is an example of C source that defines a function and of the 
resulting assembly language code. 

C source: 

power(x, n) /* Beginning of a function 

*/ 

int x,n; 

{ 

register int i, p; 

P = 1; 

for (i = 1; i <= n; ++i) p*= x; 

return p; /* End of function */ 

} 
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Resulting assembly language code: 


.sym _power,_power,36,2,0 
.global _power 

. text 
.func 1 


FUNCTION DEF 


_power:; 

INCW #4,STK 
POP A 

MOV A,-2(STK) 

POP A 

MOV A,-3(STK) 

MOV FP,-1,A 
MOV A,-1(STK) 

MOV FP,A 
MOV A,@STK 
MOVW STK,FP 
INCW #2,STK 
MOV R2 3,A 

MOV A,-1(STK) 

MOV R24,A 
MOV A,@STK 
.sym _x,-4,4,9,8 

-sym _n,-5,4,9,8 

.sym _i,2 3,4,4,8 

.sym _p,2 4,4,4,8 

■ line 3 
.line 5 

MOV #01h,R24 
.line 6 

MOV #01h,R23 
JMP L2 

LI : 

MOV -4 (FP) , A 
MPY R24,A 
MOV B,R24 
INC R23 

L2 : 

MOV -5 (FP) , A 
CMP R23,A 
JGE LI 
.line 7 
MOV R24,R8 
EPI0_1: 

.line 8 
MOV @STK,A 
MOV A,R24 
MOV -1(STK),A 
MOV A,R23 
MOVW FP,STK 
MOV @STK,A 
MOV A,FP 
MOV -1(STK),A 
MOV A,FP-1 
MOV -2(STK),A 
MOV A,B 
MOV -3(STK),A 

INCW #-4,STK 
BR @R1 

.endfunc 8,00180H,OOOOOH,0 
. end 
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Syntax .line line number [, address] 

Description The .line directive creates a line number entry in the object file. Line 

number entries are used in symbolic debugging to associate 
addresses in the object code with the lines in the source code that 
generated them. 

The .line directive has two operands: 

• Line number indicates the line of the source that generated a 
portion of code. Line numbers are relative to the beginning of the 
current function. This is a required parameter. 

• Address is an expression that is the address associated with the 
line number. This is an optional parameter; if you don't specify an 
address, the assembler will use the current SPC value. 

Example The .line directive is followed by the assembly language source 

statements that are generated by the indicated line of C source. For 
example, assume that the lines of C source below are lines 5 and 6 in 
the original C source; lines 5 and 6 produce the assembly language 
source statements that are shown below. 

C source: 

for (p = 1; i = 1; i <= n; ++i) p*=x 
return p; 

Resulting assembly language code: 

.line 5 
MOV #01h, R24 
MOV #01h, R23 
JMP L2 

LI: 

MOV -4(FP), A 
MPY R24, A 
MOV B, R24 
INC R23 

L2 : 

MOV -5(FP), A 
CMP R23, A 
JGE LI 
.line 6 
MOV R24, R8 


B-8 




MSP430 Family 


Symbolic Debugging Directives 


Syntax 

Description 


Example 


.member name, value [, type, storage class, size, tag, dims] 

The .member directive defines a member of a structure, union, or 
enumeration. It is valid only when it appears in a structure, union, or 
enumeration definition. 

• Name is the name of the member that is put in the symbol table. 
The first 32 characters of the name are significant. 

• Value is the value associated with the member. Any legal 
expression (absolute or relocatable) is acceptable. 

• Type is the type of the member. Appendix A contains more 
information about types. 

• Storage class is the storage class of the member. Appendix A 
contains more information about storage classes. 

• Size is the number of bits of memory required to contain this 
member. 

• Tag is the name of the type (if any) or structure of which this 
member is a type. This name must have been previously declared 
by a .stag, .etag, or .utag directive. 

• Dims may be one to four expressions separated by commas. This 
allows up to four dimensions to be specified for the member. 

The order of parameters is significant. Name and value are required 
parameters. All other parameters may be omitted or empty (adjacent 
commas indicate an empty entry). This allows you to skip a parameter 
and specify a parameter that occurs later in the list. Operands that are 
omitted or empty assume a null value. 

Here is an example of a C structure definition and the corresponding 
assembly language statements: 

C source: 

struct doc { 

char title; 
char group; 
int job_number; 

} doc_info; 

Resulting assembly language code: 

.stag doc,24 
.member _title,0,2,8,8 
.member _group,8,2,8,8 
.member _j ob_number,16,4,8,8 
. eos 
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.stag name [, size] 
member definitions 

.eos 

.etag name [, size] 
member definitions 

.eos 

.utag name [, size] 
member definitions 

.eos 

The .stag directive begins a structure definition. The .etag directive 
begins an enumeration definition. The .utag directive begins a union 
definition. The .eos directive ends a structure, enumeration, or union 
definition. 

Name is the name of the structure, enumeration, or union. The first 32 
characters of the name are significant. This is a required 
parameter. 

Size is the number of bits the structure, enumeration, or union 
occupies in memory. This is an optional parameter; if omitted, 
the size is unspecified. 

The .stag, .etag, or.utag directive should be followed by a number of 
.member directives, which define members in the structure. The 
.member directive is the only directive that can appear inside a 
structure, enumeration, or union definition. 

The assembler does not allow nested structures, enumerations, or 
unions. A C compiler “unwinds" nested structures by defining them 
separately and then referencing them from the structure they are 
referenced In. 

Here is an example of a structure definition. 

C source: 

struct doc 
{ 

char title; 
char group; 
int j ob_number; 

} doc_info; 

Resulting assembly language code: 

.stag _doc,24 
.member _title,0,2,8,8 
.member _group,8,2,8,8 
.member _j ob_number,16,4,8,8 
. eos 
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Here is an example of a union definition. 

C source: 

union u_tag { 
int vail; 
float val2; 
char vale; 

} va1u; 

Resulting assembly language code: 

•utaa _u_tag,24 

I' _vall, 0,4,11,8 
.member _val2,0,6,11,24 
.membc"^ _valc, 0,2,11,8 
. eos 

Here is an example of an enumeration definition. 

C Source: 

{ 

enum o_ty { reg_l, reg_2, result } optypes; 

Resulting assembly language code: 

.etag _o_ty,8 
.member _reg_l,0,4,16,8 
.member _reg_2,1,4,16,8 
.member _result,2,4,16,8 
. eos 
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.sym name, value [, type, storage class, size, tag, dims] 

The .sym directive specifies symbolic debug information about a global 
variable, local variable, or a function. 

• Name is the name of the variable that is put in the object symbol 
table. The first 32 characters of the name are significant. 

• Value is the value associated with the variable. Any legal expres¬ 
sion (absolute or relocatable) is acceptable. 

• Type? is the type of the variable. Appendix A contains more 
information about types. 

• Storage class? is the storage class of the variable. Appendix A 
contains more information about storage classes. 

• Size? is the number of bits of memory required to contain this 
variable. 

• Tag is the name of the type (if any) or structure of which this 
variable is a type. This name must have been previously declared 
by a .stag, .etag, or .utag directive. 

• Dims may be up to four expressions separated by commas. This 
allows up to four dimensions to be specified for the variable. 

The order of parameters is significant. Name and value are required 
parameters. All other parameters may be omitted or empty (adjacent 
commas indicate an empty entry). This allows you to skip a parameter 
and specify a parameter that occurs later in the list. Operands that are 
omitted or empty assume a null value. 

These lines of C source produce the .sym directives shown below: 

C source: 

struct s { int member1, member2; } str; 
int ext; 

int array[5] [10] ; 
long *ptr; 
int strcmp(); 

main(argl,arg2) 
int argl; 
char *arg2; 

{ 

register rl; 

} 
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Resulting 

assembly language code: 

. sym 

_str,_str,8,2,16,_s 

. sym 

_ext,_ext,4,2,8 

. sym 

_array,_array,244,2,400,,5,10 

. sym 

_ptr,_ptr,21,2,16 

. sym 

_main,_main,36,2,0 

. sym 

_argl,-4,4,9,8 

. sym 

_arg2,-6,18,9,16 

. sym 

_rl,23,4,4,8 
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22 Assembler Error Messages 

The assembler issues several types of error messages: 

• Fatal 

• Nonfatal 

• Macro 

When the assembler completes its second pass, it reports any errors that it encountered 
during the assembly. It also prints these errors in the listing file (if one is created); an error is 
printed following the source line that incurred it. 

This appendix discusses the three types of assembler error messages; they are listed in 
alphabetical order. Most errors are fatal errors; if an error is not fatal or if it is a macro error, 
this is noted in the list. 

absolute value required: A relocatable symbol was used where an absolute symbol was 
expected. 

a component of the expression is invalid 

address required: The operand of the flagged directive must be an address 

an identifier in the expression is invalid 
argument must be character constant 
bad indirect address 
bad macro library format 
.break encountered outside loop block 
cannot equate an external to an external 

cannot open library: A library name specified with the .mlib directive does not exist or is 
already being used. 

cannot redefine register: Register names cannot be used as labels. 

character constant overflows a word 

close 0) missing: Mismatched parentheses. 

close (]) missing: Mismatched brackets. 

close quote missing: All strings must be enclosed in quotes. 

comma missing: The assembler expected a comma but did not find one. This usually 
means that more operands were expected. 

conditional block nesting level exceeded 
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conflicts with previous section definition 

copy file open error: A file specified by a .copy directive does not exist or is already being 
used. 

directive only valid if (-a) option use: The .setsect and .setsym directives can be used only 
if the -a (absolute list) option is specified. 

divide by zero: An expression or well-defined expression contains invalid division. 

duplicate definition: The symbol appears as an operand of a REF statement, as well as in 
the the label field of the source, or the symbol appears more than once in the label field of 
the source. 

duplicate definition of a structure component 

.else or .elseif needs corresponding .if: An .else or .elseif directive was not preceded by 
an .if directive. 

empty structure 

expression changed values due to jump expansion: An expression is dependent on the 
amount of code between 2 labels. If the assembler expands a jump in the code between 
these 2 labels, then this expression will evaluate to different values in pass1 and pass2. 
Between the 2 labels, you will need to manually expand any jumps in your source code 
which were automatically expanded by the assembler. 

expression not terminated properly 

expression out of bounds 

filename missing: The specified filename cannot be found. 

floating-point expression not allowed 
floating-point number not valid in expression 

illegal label: A label cannot be used for the second instruction of a parallel instruction pair. 

illegal operation in expression 

illegal structure definition 

illegal structure member 

illegal structure, union, or enumeration tag 

illegal relative address: The label destination of a relative jump must be defined within the 
same section as the jump. 

illegal symbolic address: Operand only valid in absolute address mode. 

illegal use of local label: Local labels are not allowed in expressions. 

invalid binary constant: The only valid binary integers are 0 and 1; the constant must be 
suffixed with b or B. 
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invalid bit number: You must specify a bit number between 0 and 7. 

invalid decimal constant; The only valid decimal integers are 0-9. 

invalid expression: This may indicate invalid use of a relocatable symbol in arithmetic. 

invalid floating-point constant 

invalid octal constant: The only valid octal digits are the integers are 0-8; the constant must 
be suffixed with q or Q. 

invalid opcode; The command field of the source record has an entry that is not a defined 
instruction, directive, or macro name. 

invalid operand or operand combination 

invalid option: An option specified by the .option directive is invalid. 

invalid subscript or index 
invalid symbol qualifier 

invalid trap number: Trap numbers must be absolute values between 0 and 15. 
label required: The flagged directive must have a label. 

library not in archive format: A file specified with an .mlib directive is not an archive file. 

local label multiply defined in block 
local label not defined in block 
local macro variable is not a valid symbol 
macro parameter Is not a valid symbol 
maximum macro nesting level exceeded 
maximum number of copy files exceeded 
.mexit directive encountered outside macro 
missing .endif directive 
missing .endloop directive 
missing .endm directive 
missing macro name 
missing structure tag 

no include/copy files in macro or loop blocks 
no parameters for macro arguments 

no relative jumps to symbols not In current section: Relative jumps to load-time 
addresses defined with the .label directive are not allowed. 

offset must point to even (word) address 
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open “(“ expected 

operand missing; An operand must be supplied. 

operand must be an immediate vaiue 

pass1/pass2 operand confiict: A symbol in the symbol table did not have the same value in 
pass 1 and pass 2. 

positive value required 

redefinition of local substitution symbol 

register symbol used before definition: Equating a symbol to a register must be done 
before first symbol use. 

relative jumps to externals are not allowed 

string required: You must supply a string that is enclosed in double quotes. 

substitution symbol stack overflow 
substitution symbol string too long 

subtraction of labels not allowed: Subtraction of labels or relationals involving the amount 
of code between labels is not allowed in expressions used in some contexts. 

symbol required: The .global directive requires a symbol as an operand. 

symbol used In both REF and DEF: A REFed symbol is already defined. 

syntax error 

target address not word aligned 
too many local substitution symbols 

unbalanced symbol table entries: For .block and .func directives, 
undefined structure member 
undefined structure tag 
undefined substitution symbol 

undefined symbol: An undefined symbol was used where a well-defined expression is 
required. 

underflow in floating-point constant: Floating-point value is too small to represent. 

unexpected .endif encountered: An .endif directive was not preceded by a .loop directive. 

unexpected .endloop encountered; An .endloop directive was not preceded by a .loop 
directive. 

unexpected .endm directive encountered 

unexpected .endstruct directive encountered; An endstruct directive was not preceded 
by a .struct directive. 
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value is out of range 

.var directive encountered outside macro 

version number changed 

warning — block open at end of file 

warning — function .sym required before .func 

warning — immediate operand not absolute 

warning — line truncated 

warning — register converted to immediate 

warning — string length exceeds maximum limit 

warning — symbol truncated: The maximum length for a symbol is eight characters. The 
assembler ignores the extra characters. 

warning — trailing operand(s): The assembler found fewer or more operands than 
expected in the flagged instruction. 

warning — value out of range 

warning — value truncated: The expression given was too large to fit within the instruction 
opcode or the required number of bits. 
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23 Linker Error Messages 


The linker issues several types of error messages: 

• Syntax and command errors 

• Allocation errors 

• I/O errors 

This appendix discusses the three types of errors; they are listed alphabetically within each 
category. In these listings, the symbol (...) represents the name of an object that the linker is 
attempting to interact with when an error occurs. 

• Syntax/Command Errors 

These errors are caused by incorrect use of linker directives, misuse of an input 
expression, or invalid options. Check the syntax of all expressions, and check the input 
directives for accuracy. Review the various options you are using and check for conflicts. 

absolute symbol (...) being redefined: An absolute symbol cannot be redefined. 

adding name (...) to multiple output sections: The input section is mentioned twice in 
the SECTIONS directive. 

ALIGN illegal in this context: Alignment of a symbol can be performed only within a 
SECTIONS directive. 

attempt to decrement DOT: Statements such as .-= value are illegal. Assignments to 
dot can be used only to create holes. 

bad fill value: The fill value must be a 16-bit constant. 

binding address for (...) redefined: Only one binding value is allowed for each section, 
blocking for (...) redefined: Only one blocking value is allowed for each section. 

can't open filename: Specified filename cannot be opened for some reason; file doesn't 
exist, wrong file type, etc. 

cannot specify both binding and memory area for (...): The two are mutually 
exclusive. If you wish the code to be placed at a specific address, use binding only. 

cannot specify a page for a section within a GROUP 

command file nesting exceeded with file (...): Command file nesting is allowed up to 
16 levels. 

-e flag does not specify a legal symbol name (...): The -e option requires a valid 
symbol name as an operand. 

entry point symbol (...) undefined: The symbol used with the -e option is not defined, 
errors in input - (...) not built: Previous errors prevent the creation of an output file. 

fill value for (...) redefined: Only one fill value is allowed per output section. Individual 
holes can be filled with different values with the section definition. 
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-i path too long (...): The maximum number of characters in an -i path is 256. 

illegal input character: There is a control character or other unrecognized character in 
the command file. 

illegal memory attributes for (...): The attributes must be some combination of R, W, I, 
and X. 

illegal operator In expression: Review legal expression operators. 

illegal option within SECTIONS: The -I (lowercase L) is the only option allowed within a 
SECTIONS directive. 

invalid path specified with -i flag: The operand of the -i flag must be a valid file or 
pathname. 

invalid value for -f flag: must be a 2-byte constant, 
invalid value for -heap flag: must be a 2-byte constant, 
invalid value for -stack flag: must be a 2-byte constant, 
invalid value for -v flag: must be a constant. 

length redefined for memory area (...): Each memory area in a MEMORY directive can 
have only one length. 

-m flag does not specify a valid filename: You must specify a valid filename to write 
the output map file to. 

memory area for (...) redefined: Only one named memory allocation is allowed for each 
output section. 

memory page for (...) redefined: Only one page allocation is allowed for each section. 

memory attributes redefined for (...): Only one set of memory attributes is allowed for 
each output section. 

missing filename on -I; use -I <filename>: The -I (lowercase L) option requires the use 
of a filename operand. 

misuse of DOT symbol in assignment instruction: The dot symbol cannot be used in 
assignment statements that are outside SECTIONS directives. 

no input files: The linker cannot operate without at least one input COFF file. 

-o flag does specify a vaiid fiie name : string 

output file has no .bss section: This is a warning. This section is usually present in a 
COFF file. There is no real requirement for it to be present. 

output file has no .data section: This is a warning. This section is usually present in a 
COFF file. There is no real requirement for it to be present. 

output file has no .text section: This is a warning. This section is usually present in a 
COFF file. There is no real requirement for it to be present. 

origin missing for memory area (...) 
origin redefined for memory area (...) 
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-r incompatible with -s (-s ignored): Since the -s option strips the relocation information 
and -r requests a relocatable object file, these options are in conflict with each other. 

section (...) not built: The most likely cause of this is a syntax error in the SECTIONS 
directive. 

semicolon required after assignment: There is a syntax error in the command file, 
statement ignored: Caused by a syntax error in an expression. 

symbol referencing errors — (...) not built 

symbol (...) from file (...) being redefined: A defined symbol cannot be redefined in an 
assignment statement. 

too many arguments - use a command file: You are limited to ten arguments on a 
command line, or in response to prompts. ^ 

too many -i options, 7 allowed: Additional search directories can be specified with a 
C_DIR or A_DIR environment variable. 

type flags for (...) redefined: Only one section type is allowed per section. Note that 
type COPY has all of the attributes of type DSECT, so DSECT need not be specified 
separately. 

type flags not allowed for GROUP or UNION: Special section types apply to individual 
sections only. 

-u does not specify a legal symbol name: The -u option must specify a legal symbol 
name that exists in one of the files that you are linking. 

unexpected EOF(end of file): Syntax error in the linker command file. 

undefined symbol in expression: An assignment statement contains an undefined 
symbol. 

unrecognized option (...): Check the list of valid options. 

zero or missing length for memory area (...): Each memory range defined with the 
MEMORY directive must have a nonzero length. 
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• Allocation Errors 

These error messages appear during the allocation phase of linking. They generally 
appear if a section or group does not fit at a certain address or if the MEMORY and 
SECTIONS directives conflict in some way. If you are using a linker command file, check 
that MEMORY and SECTIONS directives allow enough room to ensure that no sections 
overlap and that no sections are being placed in unconfigured memory. 

alignment for (...) must be a power of 2: Section alignment must be a power of 2. 
alignment for (...) redefined: Only one alignment is allowed for each section. 

binding address (...) for section (...) is outside all memory on page (...): Each section 
must fall within memory configured with the MEMORY directive. 

binding address (...) for section (...) overlays (...) at (...): Two sections overlap and 
cannot be allocated. 

binding address (...) incompatible with alignment for section (...): The section has an 
alignment requirement from a .align directive or previous link. The binding address 
violates this requirement. 

blocking for (...) must be a power of 2: Section blocking must be a power of 2. 

can't align a section within GROUP - (...) not aligned: The entire GROUP is treated as 
one unit, so the GROUP can be aligned or bound to an address, but the sections making 
up the GROUP cannot be handled individually. 

can't align within UNION - section (...) not aligned: The entire UNION is treated as 
one unit, so the UNION can be aligned or bound to an address, but the sections making 
up the UNION cannot be handled individually. 

can't allocate (...), size ... (page ...): A section can't be allocated, because no configured 
memory area exists that is large enough to hold it. 

load address for uninitialized section (...) ignored: Uninitialized sections have no load 
addresses—only run addresses. 

load address for UNION ignored: UNION refers only to the section's run address. 

load allocation required for uninitialized UNION member (...): UNIONS refer to 
runtime allocation only. You must specify the load address for all sections within a 
UNION separately. 

no allocation allowed for uninitialized UNION member: An uninitialized section with a 
UNION gets its run allocation from the UNION and has no load address, so no allocation 
is valid for the member. 

no allocation allowed with a GROUP-ailocation for section (...) ignored: The entire 
group is treated as one unit, so the group can be aligned or bound to an address, but the 
sections making up the group cannot be handled individually. 

no load address specified for (...); using run address: If an initialized section has a 
run address, only the section is allocated to run and load at the same address. 

no run allocation allowed for union member (...): A UNION defines the run address for 
all of its members; therefore, individual run allocations are illegal. 
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output file (...) not executable: The output file created may have unresolved symbols or 
other problems stemming from other errors. This condition is not fatal. 

PC-relative displacement overflow at address (...) in file (...): relocation of a PC- 
relative jump resulted in a jump displacement too large to encode in the instruction. 

section (...) at (...) overlays at address (...): The two sections overlap and cannot be 
allocated. 

section (...) enters unconfigured memory at address (...): A section can't be allocated 
because no configured memory area exists that is large enough to hold it. 

section (...) not found: An input section specified in a SECTIONS directive was not 
found in the input file. 

section (...) won't fit into configured memory: A section can't be allocated, because no 
configured memory area exists that is large enough to hold it. 

undefined symbol (...) first referenced in file (...): Unless the -r option is used, the 
linker requires that all referenced symbols be defined. This condition prevents the 
creation of an executable output file. 
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• i/0 and Internal Overflow Errors: 

The following error messages indicate that the input file is corrupt, nonexistent, or 
unreadable, or that the output file cannot be opened or written to. Messages in this 
category may also indicate that the linker is out of memory or table space. Make sure 
that the input file is in the correct directory and that the file system is not out of space. If 
the input file is corrupt, try reassembling it. 

cannot complete output file (...), write error: Usually means that the file system is out 
of space. 

cannot create output file (...): Usually indicates an illegal filename. 

can't find input file fiiename: 

can't open (...): The specified file does not exist. 

can't read (...) 

can't seek (...) 

can't write (...) 

can't create map file (...): Usually indicates an illegal filename. 

fail to copy (...) 

fail to read (...) 

fail to seek (...) 

fail to skip (...) 

fail to write (...) 

file (...) has no relocation information: You have attempted to relink a file that was not 
linked with -r. 

file (...) is of unknown type, magic number = (...): The binary input file is not a COFF 
fi?e. 

illegal relocation type (...) found in section(s) of file (...): The binary file is corrupt, 
internal error (...): Indicates an internal error is in the linker, 
invalid archive size for file (...): The archive file is corrupt. 

I/O error on output file (...) 

library (...) member (...) has no relocation information 

line number entry found for absolute symbol: The input file is corrupt. 

making aux entry filename ior symbol n out of sequence: The input file is corrupt. 

no string table in file filename: The input file is corrupt. 

no symbol map produced - not enough memory: This is a nonfatal condition that 
prevents the generation of the symbol list in the map file. 

overwriting aux entry filename of symbol n: The input file is corrupt, 
out of memory, aborting: 
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relocation entries out of order in section (...) of file (...): The input file is corrupt, 
relocation symbol not found: index (...), section (...), file (...): The input file is corrupt, 
seek to (...) failed 

too few symbol names in string table for archive n: The archive file is corrupt. 
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A 


absolute address: An address that is permanently assigned to a memory 
location. 

absolute lister: a debugging tool that allows you to create assembler listings 
that contain absolute addresses. 

alignment: A process in which the linker places an output section at an address 
that falls on an n-bit boundary, where n is a power of 2. You can specify 
alignment with the SECTIONS linker directive. 

allocation: A process in which the linker calculates the final memory addresses 
of output sections. 

archive library: A collection of individual files that have been grouped into a 
single file. 

archiver: A software program that allows you to collect several individual files 
into a single file called an archive library. The archiver also allows you to 
delete, extract, or replace members of the archive library, as well as to add 
new members. 

assembler: A software program that creates a machine-language program 
from a source file that contains assembly language instructions, directives, 
and macro directives. The assembler substitutes absolute operation codes 
for symbolic operation codes, and absolute or relocatable addresses for 
symbolic addresses. 

assembly-time constant: A symbol that is assigned a constant value with the 
.set or .equ directive. 

assignment statement: A statement that assigns a value to a variable. 

auxiliary entry: The extra entry that a symbol may have in the symbol table 
and that contains additional information about the symbol (whether the 
symbol is a filename, a section name, a function name, etc.). 
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binding: A process in which you specify a distinct address for an output section 
or a symbol. 

block: A set of declarations and statements that are grouped together with 
braces. 

.bss: One of the default COFF sections. You can use the .bss directive to 
reserve a specified amount of space in the memory map that can later be 
used for storing data. The .bss section is uninitialized. 

byte: A sequence of 8 adjacent bits operated upon as a unit. 



C compiler: A program that translates C source statements into assembly 
language source statements. 

command file: A file that contains linker options and names input files for the 
linker. 

comment: A source statement (or portion of a source statement) that is used to 
document or improve readability of a source file. Comments are not 
compiled, assembled, or linked; they have no effect on the object file. 

common object file format (COFF): An object file that promotes modular 
programming by supporting the concept of sections. 

conditional processing: A method of processing one block of source code or 
an alternate block of source code, according to the evaluation of a specified 
expression. 

configured memory: Memory that the linker has specified for allocation. 

constant: A numeric value that can be used as an operand. 

cross-reference listing: An output file created by the assembler that lists the 
symbols that were defined, what line they were defined on, which lines 
referenced them, and their final values. 



.data: One of the default COFF sections. The .data section is an initialized 
section that contains initialized data. You can use the .data directive to 
assemble code into the .data section. 

directive: Special-purpose commands that control the actions and functions of 
a software tool (as opposed to assembly language instructions, which 
control the actions of a device). 
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emulator: A hardware development system that emulates MSP430 operation. 

entry point: The starting execution point in target memory. 

executable module: An object file that has been linked and can be executed in 
a MSP430 system. 

expression: A constant, a symbol, or a series of constants and symbols 

separated by arithmetic operators. 

external symbol: A symbol that is used in the current program module but 
defined in a different program module. 



field: For the MSP430, a software-configurable data type whose length can be 
programmed to be any value in the range of 1-16 bits. 

file header: A portion of a COFF object file that contains general information 
about the object file (such as the number of section headers, the type of 
system the object file can be downloaded to, the number of symbols in the 
symbol table, and the symbol table's starting address). 


G 


global: A kind of symbol that is either 1) defined in the current module and 
accessed in another, or 2) accessed in the current module but defined in 
another. 

GROUP: An option of the SECTIONS directive that forces specified output 

sections to be allocated contiguously (as a group). 


H 


high-level language debugging: The ability of a compiler to retain symbolic 
and high-level language information (such as type and function definitions) 
so that a debugging tool can use this information. 

hole: An area between the input sections that compose an output section that 
contains no actual code or data. 



incremental linking: The linking of files that have already been linked. 
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initialized section: A COFF section that contains executable code or initialized 
data. An initialized section can be built up with the .data, .text, or .sect 
directive. 

Input section: A section from an object file that will be linked into an executable 
module. 



label: A symbol that begins in column 1 of a source statement and corresponds 
to the address of that statement. 

line number entry: An entry in a COFF output module that maps lines of 
assembly code back to the original C source file that created them. 

linker: A software tool that combines object files to form an object module that 
can be allocated into system memory and executed by the device. 

listing file: An output file created by the assembler that lists source statements, 
their line numbers, and their effects on the SPC. 

loader: A device that loads an executable module into system memory. 


M 


member: The elements or variables of a structure, union, or enumeration. 

macro: A user-defined routine that can be used as an instruction. 

macro call: The process of invoking a macro. 

macro definition: A block of source statements that define the name and the 
code that make up a macro. 

macro expansion: The source statements that are substituted for the macro 
call and are subsequently assembled. 

macro library: An archive library composed of macros. Each file in the library 
must contain one macro; its name must be the same as the macro name it 
defines, and it must have an extension of .asm. 

magic number: A COFF file header entry that identifies an object file as a 
module that can be executed by the MSP430. 

map file: An output file, created by the linker, that shows the memory 
configuration, section composition, and section allocation, as well as 
symbols and the addresses at which they were defined. 

memory map: A map of target system memory space that is partitioned into 
functional blocks. 

mnemonic: An instruction name that the assembler translates into machine 
code. 
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are assembled each time a macro is invoked. 
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named section: An initialized section that is defined with a .sect directive, or an 
uninitialized section that is defined with a .usect directive. 


o 


object file: A file that has been assembled or linked and contains machine- 
language object code. 

object format converter: A program that converts COFF object files into Intel- 
format, Tektronix-format, Tl-tagged format, or Motorola-S format object 
files. 

object library: An archive library made up of individual object files. 

operand: The arguments, or parameters, of an assembly language instruction, 
assembler directive, or macro directive. 

optional header: A portion of a COFF object file that the linker uses to perform 
relocation at download time. 

options: Command parameters that allow you to request additional or specific 
functions when you invoke a software tool. 

output module: A linked, executable object file that can be downloaded and 
executed on a target system. 



partial linking: The linking of a file that will be linked again. 


R 


raw data: Executable code or initialized data in an output section. 

relocation: A process in which the linker adjusts all the references to a symbol 
when the symbol's address changes. 


s 


section: A relocatable block of code or data that will ultimately occupy 

contiguous space in the memory map. 

section header: A portion of a COFF object file that contains information about 
a section in the file. Each section has its own header; the header points to 
the section's starting address, contains the section's size, etc. 

section program counter: See SPC. 
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sign-extend: To fill the unused MSBs of a value with the value's sign bit. 

SPC (section program counter): An element of the assembler that keeps track 
of the current location within a section; each section has its own SPC. 

static: A kind of variable whose scope is confined to a function or a program. 
The values of static variables are not discarded when the function or 
program is exited; their previous value is resumed when the function or 
program is re-entered. 

storage class: Any entry in the symbol table that indicates how a symbol 
should be accessed. 

string table: A table that stores symbol names that are longer than 8 

characters (symbol names of 8 characters or longer cannot be stored in the 
symbol table; instead, they are stored in the string table). The name portion 
of the symbol's entry points to the location of the string in the string table. 

structure: A collection of one or more variables grouped together under a 

single name. 

symbol: A string of alphanumeric characters that represents an address or a 
value. 

symbolic debugging: The ability of a software tool to retain symbolic 

information so that it can be used by a debugging tool such as a simulator or 
an emulator. 

symbol table: A portion of a COFF object file that contains information about 
the symbols that are defined and used by the file. 



tag: An optional “type" name that can be assigned to a structure, union, or 
enumeration. 

target memory: Physical memory in a MSP430-based system into which 
executable object code is loaded. 

.text: One of the default COFF sections; an initialized section that contains 

executable code. You can use the .text directive to assemble code into the 
.text section. 


u 


unconfigured memory: Memory that is not defined as part of the memory map 
and cannot be loaded with code or data. 

uninitialized section: A COFF section that reserves space in the memory map 
but that has no actual contents. These sections are built up with the .bss, 
.reg, and .usect directives. 
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union: A variable that may hold (at different times) objects of different types and 
sizes. 

unsigned: A kind of value that is treated as a positive number, regardless of its 
actual sign. 


w 


weli-defined expression: An expression that contains only symbols or 

assembly-time constants that have been defined before they appear in the 
expression. 

word: A 16-bit addressable location in target memory. 
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26 Floating Point Formats 

All MSP430 floating-point formats consist of three fields: an exponent field (e), a single-bit 
sign field (s), and a fraction field (f). The sign field and fraction field may be considered as 
one unit and referred to as the mantissa field. The fraction contains an implied most- 
significant bit, which is always 1 for a correctly represented floating-point constant. This 
provides an additional bit of precision. The exponent is bias 128; that is, subtract 128 from 
the unsigned value of the 8 exponent bits to arrive at an actual value for the exponent. A 
sign, exponent and fraction of zero is used as a special representation of value zero. 
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26.1 Single Precision Format 

In the single precision format, the floating-point number is represented by an 8-bit exponent, 
a sign bit and a 23-bit fraction. 

The format is as follows: 


eTe e e ae^ [s f f f f f fj [f f f f f f fl] [f f f f f f f f 


The fraction contains 23 actual bits plus an implied bit fo, always representing a 1. The value 
of each f; is arrived at through this formula: 

^ 23 23 ^ 

f, = 1 => f = y fi = y 1 

2 ' 2 ' 


Therefore, the layout in terms of values is 
^1111111 1 1 

’ 2’ 4’ 8’ 16’ 32’ 64’ 128’ 256’ 512’ 


Example: Calculating the fraction (80 in those examples is the exponent) 

f: 


Floating Point Value 

80100000 

80310000 


1,1 

8 

1 . 

4 8 128 


1 


Fraction Decimal Equivalent 

1 + - = 1.125 
8 

1 + - + - + — = 1.3828125 
4 8 128 


Given the above format, some examples of acceptable floating-point values are shown in the 
following examples. 


Example: Calculating Floating-Point Values 


SIdOOOOO 


Exponent 


Sign 


1 

L° 

A 

0 

0 


0 

1 


o[~^~(^ o| 0 


0 0 


0 0 0 


The encoded exponent equals 129; the real exponent equals 129-128 = 1. 
The fraction equals 1 (implied fo) ^ ^ ~ ^.625 . 

The following formula expresses the actual value of the floating-point number: 

3 X f X 26-128 
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where s is the sign of the number (either 1 or - 1 ), f is the value of the fraction ( 1.0 < f < 
2 . 0 ) and e is the represented value of the exponent. 

Therefore, the floating-point value is 

-1 X 1.625 2^29-128 =: . 3,25 


The following list gives other examples of proper floating-point values derived from the above 
formulas. 


SOOOOOOOh 

=> 

1.0 

81500000h => 

3.25 

80800000h 

=> 

- 1.0 

8f3b8000h => 

4.8e4 

OOOOOOOOh 

=> 

0.0 

840c0000h => 

1.75e1 

83200000h 

=> 

I.Oel 

79937500h => 

- 9.0e-3 


26.2 Double Precision Format 

The only difference to the single precision format is the length of the fraction: 

[eeeeeeee[ |s f f f f f f fj |f f f f f f f fj |fYf'f f fT’fj jYTYfl fTf| [f YfYYf f f| 

Here it contains 39 actual bits plus an implied bit fo; so the summation formation for the 
fraction changes to: 
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A__DIR 

assembler 8-12, 8-13 
A__DiR (assembler) 3-7, 3-8 
abbreviations and symbols 5-4 
absolute lister 9-3 

creating the absolute listing file 3-5 
examples 9-6 
invoking 9-5 

absolute output module 8-10 
addressing modes 5-5 
alignment 4-13, 4-20, 8-28 
allocation 2-4, 2-11, 8-26 
alignment 4-20, 8-28 
binding 8-26 
blocking 8-28 
GROUP 8-38 
named memory 8-27 
of output sections 8-22 
UNION 8-35 
alternate directories 

naming with -i option 3-7 
naming with A_DIR 3-7 
naming with C_DIR 
linker 8-12 

naming with the -I option 
linker 8-12 
ar370 command 7-5 
archive libraries 3-7, 4-48, 7-3, 8-12, 
8-15, 8-19 

back referencing 8-15 
archiver 7-3 
examples 7-7 
input 7-3 
invocation 7-5 
options 7-5 

arithmetic operators 3-19 
asm370 command 3-5 
assembler 3-3 

character strings 3-14 
constants 3-12 

cross_reference listings 3-3, 3-26 


error messages C-3 

expressions 3-18, 3-19, 3-20, 3-21, 

3-22 

invocation 3-5 
macros 6-3 
output 3-23, 4-14 

list options 4-50, 4-52 
listing 4-14, 4-24, 4-44 
enable 4-44 
length 4-14, 4-43 
suppress 4-44 
width 4-14, 4-43 
listing title 4-64 
macro listing 4-48, 4-50 
page control 4-54 
relocation 2-14 
source listings 3-23, 3-25 
source statement format 3-9, 3-10, 
3-11 

symbols 2-17, 3-15 

assembler directives see also directives 
.align 4-13, 4-20 
.asg 4-7, 4-17, 4-19, 4-21, 6-8 
.block B-4 

.break 4-16, 4-46, 6-16 
.bss 4-8, 4-23 
holes 8-48 
initializing 8-48 
linker definition 8-44 
section 8-45, A-5 
.byte 4-10, 4-24 
.cinit 

linker definition 8-45 
section 8-52 
.copy 3-7, 4-15, 4-24 
.data 4-8, 4-27 

linker definition 8-44 
section 4-27, A-5 
.def 4-15, 4-37 
.else 4-16, 4-40, 6-16 
.elseif 4-16, 4-40, 6-16 
.emsg 4-18, 4-29, 6-20 
.end 4-18, 4-30 
.endblock B-4 
.endfunc B-4, B-6 
.endif 4-16, 4-40, 6-16 
.endloop 4-16, 4-46, 6-16 
.endm 6-5 
.endstruct 4-17,4-61 
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.eos B-4, B-10 
.equ 4-17, 4-56 
.etag B-4, B-10 
.eval 4-17,4-21,6-9 
.fclist 4-14, 4-32, 6-21 
.fcnolist 4-14, 4-32, 6-21 
.field 4-11,4-13,4-33 
.file B-4, B-5 
.float 4-10,4-36 
■func B-4, B-6 
.global 2-17, 4-15, 4-37 
.heap 

section 8-52 
.hstack 

section 8-52 
.if 4-16, 4-40, 6-16 
.include 3-7,4-15,4-24 
.label 4-18, 4-42 
.lenght 4-14, 4-43 
.line B-4, B-8 
.list 4-14, 4-44 
.loop 4-16, 4-46, 6-16 
default value 6-16 
.macro 6-5 
libraries 3-7 
.member B-9 
.mexit 

macro directive 6-5 
.mlib 3-7, 4-15, 4-48, 6-15 
.mlist 4-14, 4-50, 6-21 
.mmsg 4-18, 4-29, 6-20 
.mnolist 4-14, 4-50, 6-21 
.newblock 4-17, 4-51 
.nolist 4-14, 4-44 
.option 4-14, 4-52 
.page 4-14, 4-54 
.ref 4-15, 4-37 
.sect 4-8, 4-55 
section 4-7 
.set 4-17,4-56 
.setsect 4-18 
.setsym 4-18 
.space 4-10,4-11,4-58 
.sslist 4-14, 4-59, 6-21 
.ssnolist 4-14, 4-59, 6-21 
.sstack 

section 8-52 


.stag 4-17, See structure tag, 4-61, 

B-4, B-10 

.string 4-10, 4-24 

.struct 4-17,4-61 

.sym B-4, B-12 

.tag 4-17,4-61 

.text 2-4, 2-6, 2-7, 2-8, 2-12, 2-13, 
2-14, 4-8, 4-27, 4-63 
linker definition 8-44 
section A-5 
■title 4-14, 4-64 
-usect 2-6, 2-7, 4-8, 4-65 
.utag B-4, B-10 
•var 

macro directive 6-14 
.width 4-14, 4-43 
.wmsg 4-18, 4-29, 6-20 
.word 4-10, 4-67 
assembler output 
list options 4-52 
listing 4-14, 4-24, 4-44 
enable 4-44 
length 4-43 
suppress 4-44 
width 4-43 
listing title 4-64 
macro listing 4-48, 4-50 
page control 4-54 
assembly language development flow 
7-4, 8-6 

assembly_time constants 4-56 
assigning a value to a symbol 4-56 
autoinitialization 8-51 
RAM model 8-11,8-51 
ROM model 8-11,8-51 
auxiliary entries A-22 


B 


binary integers 3-12 
binding 8-26 
block definitions A-16, B-4 
blocking 8-28 
boot.asm 8-15 
boot.obj 8-51, 8-52 
byte alignment 4-20 
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C compiler 8-11, 8-51, A-3, B-4 
block definitions B-4 
enumeration definitions B-10 
file identification B-5 
function definitions B-6 
line number entries B-8 
line number information A-12 
member definitions B-9 
special symbols A-16 
storage classes A-19 
structure definitions B-10 
symbol table entries B-12 
union definitions B-10 
C memory pool 8-12, 8-52 
C system stack 8-52 
C_.DIR 

linker See environment variables, 
8-13 

c_intO (_cjnt0) 8-11, 8-52 
calling a macro 6-4 
character strings 3-14 
CI370 command B-3 
Clock cycles 5-8 
code conversion 10-3 
COFF 2-3, 8-5, 10-3, A-3 
auxiliary entries A-22 
default sections 2-4 
file headers A-6 
file structure A-4 
initialized sections 2-4 
line number table A-12 
maximum number of 2-4 
named sections 8-45 
optional file header A-7 
relocation information A-10 
section headers A-8 
sections 2-3 

default 2-4, 2-6, 4-8, 4-23, 4-27, 
4-55, 4-63 

initialized 2-4, 2-6, 4-27, 4-55, 
4-63 

maximum number of 2-8 
named 2-4, 2-7, 4-8, 4-23, 4-27, 
4-55, 4-63, 4-65, 8-45 
.text 4-63 


uninitialized 2-6, 4-8, 4-23, 4-65 
uninitialized i 2-4 
special symbols A-16 
storage classes A-19 
string table A-18 
symbol table A-14 
symbolic debugging A-12 
type entry A-21 
command 

-a (archiver) 7-5 
-d (archiver) 7-5 
-r (archiver) 7-5 
-t (archiver) 7-5 
-X (archiver) 7-5 
command files 
linker 8-16 

reserved words 8-18 
command files (linker) 8-7 
comments 

in a linker command file 8-16 
in macros 6-20 

that extend past page width 4-43 
comments . . . 

in assembly language source code 
3-11 

that extend past page width 4-43 
common object file format See COFF 
conditional assembly directives 4-16 
in macros 6-16 
maximum nesting levels 6-16 
conditional block 4-32, See conditional 
assembly directives, 4-40, See 
conditional assembly directives. See 
conditional assembly directives 
conditional expressions 3-20 
configured memory 8-39 
constants 3-12 

assembly-time 4-56 
assembly_time 4-56 
binary integers 3-12 
character 3-12 
decimal integers 3-12 
floating-point 4-36 
floating_point 4-36 
hexadecimal integers 3-12 
in linker expressions 8-43 
octal integers 3-12 
symbols as 3-12 
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copy files 3-7, 4-24 
COPY section 8-41 
creating holes 8-45 
cross_reference listings 3-3, 3-26 


debugging See symbolic debugging 
producing error messages in macros 
6-20 

decimal integers 3-12 
default 

memory allocation 2-12 
default allocation 8-39 
default fill value for holes 8-11 
default memory allocation 2-12 
default memory model 8-20 
defining macros 6-5 
directives 
section 

.bss 4-8 
.data 4-8 
.sect 4-8 
.text 4-8 
.usect 4-8 
directives, assember 
section 

.usect 4-65 

directives, assembler See assembler 
directives 

assembly-time symbols 
.asg 4-21 

.endstruct 4-17, 4-61 
.equ 4-17, 4-56 
.eval 4-17,4-21 
.set 4-17,4-56 
.struct 4-17,4-61 
.tag 4-17,4-61 
conditional assembly 
.else 4-16, 4-40 
.elseif 4-16, 4-40 
.endif 4-16, 4-40 
.if 4-16, 4-40 
directives 
.data 4-27 
miscellaneous 

.emsg 4-18, 4-29 
.end 4-18, 4-30 


.label 4-18, 4-42 
.mmsg 4-18, 4-29 
.wmsg 4-18, 4-29 
section 

.bss 2-4,2-6,2-7,2-15,4-8,4-23, 
4-27 

.data 2-4, 2-6, 2-7, 4-8, 4-27 

.emsg 4-18 

.end 4-18 

.global 4-37 

.label 4-18, 4-42 

.mmsg 4-18 

.sect 2-6, 2-7, 2-8, 4-8, 4-55 
.sect i 2-6 
.setsect 4-18 
■setsym 4-18 

.text 2-4, 2-6, 2-7, 4-8, 4-27, 4-63 
.usect 2-6, 2-7, 4-8, 4-65 
.wmsg 4-18 
summary table 4-4 
that affect assembler output 
.end 4-18, 4-30 
.length 4-43 
.list 4-44 
.mlist 4-50 
.mnolist 4-50 
.nolist 4-44 
.option 4-52 
.page 4-54 
.title 4-64 
.width 4-43 

that align the SPC 4-13 
.align 4-13, 4-20 
.field 4-13, 4-33 
that format the output listing 
.length 4-14, 4-43 
.list 4-14, 4-44 
.mlist 4-14, 4-50 
.mnolist 4-14, 4-50 
.nolist 4-14, 4-44 
.option 4-14, 4-52 
.page 4-14, 4-54 
.title 4-14,4-64 
.width 4-14, 4-43 
that initialize data 
.byte 4-24 
.equ 4-17,4-56 
.float 4-36 
.set 4-17,4-56 
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.space 4-58 
.string 4-24 
.word 4-67 
that initialize memory 
.byte 4-10, 4-24 
.field 4-10, 4-11, 4-33 
.float 4-10, 4-36 
.space 4-11,4-58 
.string 4-10, 4-24 
.word 4-10, 4-67 
that reference other files 
.copy 4-15, 4-24 
.def 4-15, 4-37 
.global 4-15, 4-37 
.include 4-15, 4-24 
.mlib 4-15, 4-48 
.ref 4-15, 4-37 

directives, conditional assembly 4-16 
directives, linker 
MEMORY 2-13 
SECTIONS 2-13 
directory search algorithm 
assembler 3-7 
linker 8-12 
□SECT section 8-41 
dummy section 8-41 


E 


edata 

linker symbol 8-44 
end 

linker symbol 8-44 
entry points 

_cjnt0 8-11,8-52 
_main 8-11 
for C code 8-52 
for the linker 8-11 
enumeration definitions B-10 
environment variables 
A_DIR 3-7, 3-8 
C„DIR 

linker 8-12, 8-13 
EPROM programmers 10-3 
error messages 
assembler C-3 
linker D-3 


producing in macros 6-20 
etext 

linker symbol 8-44 

expressions 3-18, 3-19, 3-20, 3-21, 3-22 
lett_to_right evaluation 3-18 
linker 8-43 
overflow 3-19 

parentheses effect on evaluation 
3-18 

precedence of operators 3-18 
that are well defined 3-20 
that contain arithmetic operators 3-19 
that contain conditional operators 
3-20 

that contain relocatable symbols 3-20 
underflow 3-19 

external symbols 3-20, 4-15, 4-37, 4-56 


F 


false conditional blocks See 

Jclist/.fcnolist 

file headers A-6 

file identification B-5 

filenames 

as character strings 3-14 
copy/include files 3-7 
executable code 1-7 
list file 1-7, 3-5 
macros 

in macro libraries 6-15 
object code 1-7, 3-5 
searching for, assembler 3-7 
source code 1-7, 3-5 
fill 

linker directive 8-14 

ignoring fill directive 8-14 
MEMORY specification 8-22 
fill value 8-49, See holes 
default 8-11,8-48 
flags 8-24 
setting 8-11 
flags 

fill value 8-24 

floating-point constants 4-36 
floating_point constants 4-36 
format I instructions 5-8 
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format II instructions 5-9 
format III instructions 5-9 
function definitions A-17,B-6 


G 


glossary F-3 
GROUP 

SECTIONS directive 8-38 


H 


halt conditions 10-11 
hardware stack 

changing the size of 8-15 
default size 8-15 
heap (-heap) 

linker 8-12, 8-52 
heap definition 8-12 
HEAP_SIZE (_HEAP_SIZE) 8-45 
holes 8-11,8-45 
fill value 

flags 8-24 
fill values 8-47 

ignoring fill specs 8-14 
in output sections 8-45 
in uninitialized sections 8-48 
initialized 8-49 

HSTACK_S1ZE (_HSTACK_S1ZE) 8-45 


MEMORY attribute 8-21 
i-hstack 

linker 8-52 
i-sstack 

linker 8-52 
i_HEAP_SIZE 8-52 
i_HSTACK_SIZE 8-52 
i„SSTACK_SIZE 8-52 
IBM PC/AT software installation 1-6 
iheap 

definition 8-52 
ihstack 


definition (C system) 8-52 
include file letter (source listing) 3-23 
include files 3-7, 4-24 
incremental linking 8-50 
initialized sections 8-45 
input 

linker 8-6, 8-16 
object format converter 10-9 
input.. . 

archiver 7-3 
assembler 7-3 
linker 7-3 
instruction set 

addressing modes 5-5 
Clock cycles 5-8 
Length of Instructions 5-8 
summary 5-3, 5-6 
symbols and abbreviations 5-4 
instructions 
format I 5-8 

clock cycles 5-8 
length of 5-8 
format II 5-9 

clock cycles 5-9 
length of 5-9 
format III 5-9 

clock cycles 5-9 
length of 5-9 

miscellanous instructions 5-9 

clock cycles, RETI, interrupt 5-9 
length of, RETI, interrupt 5-9 
Intel hex object format 10-3,10-6 
Intel object format 10-9 
invoking the . . . 

assembler 3-5 
invoking the ... 

absolute lister 9-5 
archiver 7-5 
linker 8-7 

object format converter 10-9 
isstack 

definition (C system) 8-52 


K 


keywords (linker) 
linker 8-18 
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labels 

case sensitivity 3-9 
defined and referenced 
(cross_.reference list) 3-26 
in assembly language source 3-9 
in macros 6-18 
local 3-15, 4-51 
resetting 4-51 
local labels 4-51 
resetting 4-51 
syntax 3-9 

using with .byte directive 4-24 
using with .word directive 4-67 
lefLto„right evaluation (of expressions) 
3-18 
length 

MEMORY specification 8-21 
Length of Instructions 5-8 
library search algorithm 
assembler 3-7 
linker 8-12 

line number table A-12 
entry format A-12 
line number blocks A-12 
removing from object module A-13 
line numbers 

from C source in assembly code B-8 
in source file listings 3-23 
stripping 8-15 
linker 8-5 

COFF 2-11, 2-12, 2-13, 8-5 
command files 8-7,8-16 
configured memory 8-39 
error messages D-3 
expressions 8-42 
incremental linking 8-50 
input 8-16 
invocation 8-7 
linking C code 8-51 
Ink370 command 8-7 
loading a program 2-16 
operators 8-43 
options summary 8-9 
relocation 2-14 
sections 2-11,2-12,2-13 


SECTIONS directive 8-23 
symbols 2-17 
unconfigured memory 8-39 
linker input 8-6 
linker options 8-9 
linker output 8-6,8-14 
linking C code 8-11 
listing 

page size 4-43 
listing . . . 

control 4-44, 4-50, 4-52, 4-54, 4-64 
file 4-14 

listing control 4-44, 4-50, 4-52, 4-54, 

4-64, 6-21 

listing file 4-14 

listing page size 4-43 

Ink example 8-53 

Ink370 

linker command 9-5 
Ink370 command 8-7,8-16 
Ink370 example 8-52 
load 

linker keyword 8-31 
load (linker keyword) 2-15 
loading a program 2-16 
local labels 3-15,4-51 
logical operators 3-19 


M 


macro directives 

summary table 6-24 
macro libraries 4-48, 6-15, 7-3 
macro parameters See substituition 
symbols 
macros 6-3 

.mlib directive 4-48 
.mlist directive 4-50 
calling 6-4 

conditional assembly 6-16 
defining a macro 6-5 
description 6-4 
directives summary 6-24 
expansion 6-4 

formatting the output listing 6-21 
labels 6-18 
libraries 4-48 
macro libraries 4-48,6-15 
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nested macros 6-22 
parameters See substitution 
symbols 

producing messages 6-20 
recursive macros 6-22 
substitution symbols 6-7 

as variables in macros 6-14 
using comments in 6-20 
main (_main) 8-11 
mallocO 8-12, 8-52 
map file 8-14 
example 8-53 
member definitions B-9 
MEMORY 

linker directive 8-20 
default model 8-20 
ignoring fill specifications 8-14 
overlay pages 8-39 
MEMORY (linker directive) 2-11 
memory map 2-13 
memory pool, C language 8-12, 8-52 
MEMORY syntax 8-20 
MEMORY_SIZE (_MEMORY_SIZE) 
8-12 

miscellanous instructions 5-9 
mnemonic field" 3-9 
syntax 3-9 

modes, addressing 5-5 

Motorola S object format 10-3, 10-8, 

10-9 


N 


named memory 8-27 

named sections 8-45, A-5 

naming an output module 8-14 

nested macros 6-22 

nesting level number (source listing) 

3-23 

NOLOAD section 8-41 


O 


object code (source listing) 3-23 
object file format See COFF 
object format converter 10-3 
examples 10-10 


input 10-9 
invocation 10-9 
output 10-9 

object formats See COFF 
Intel hex 10-3 
Motorola S 10-3 
Tektronix 10-3 
Tljagged 10-3 

object libraries 7-3, 8-12, 8-19, 8-51 
octal integers 3-12 
operands 3-9 

immediate addressing 3-10 
local label 3-15 
prefixes 3-9 
register aliasing 3-10 
operator precedence order 3-19 
option 
-a 

assembler 3-5 
linker 8-10 
-c 

assembler 3-5 
linker 8-11,8-51 
-cr 

linker 8-11,8-51 
-e 

archiver 7-5 
linker 8-11 
-f 

linker 8-11 
-hstack 

linker 8-15 
-i 

assembler 3-5, 3-7 
linker 8-12 

object format converter 10-9 
-I 

assembler 3-5 
linker 8-12 
-m 

linker 8-14, 8-39 
object format converter 10-9 
-n 

linker 8-14 
-o 

linker 8-14 

-q 

archiver 7-5 
linker 8-14 
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-r 

linker 8-10, 8-50 
-s 

archiver 7-5 
linker 8-15 
-sstack 



linker 8-15 


-I 

object format converter 

10-9 

-u 

linker 8-15 


-V 

archiver 7-5 


-X 

linker 8-15 
object format converter 
optional file header A-7 

10-9 


origin 

MEMORY specification 8-21 


output 

assembler See assembler output 
linker 8-6, 8-14 
module name 
linker 8-14 

object format converter 10-9 
sections 

rules 8-40 
output. . . 

assembler 4-14 
output listing 4-14 
overflow (in expression) 3-19 
overlay pages 8-39 

maximum number of 8-39 
PAGE definition 8-39 
using the MEMORY directive 8-39 
using the SECTIONS directive 8-39 
overlaying sections 8-35 


P 


page length 4-43 
PAGE option 

MEMORY directive 
definition 8-39 
page width 4-43 
parentheses in expressions 3-18 
partially linked files 8-50 
PC~DOS, MS-DOS, or OS/2 software 


installation 1-6 
precedence groups 3-18 
producing an absolute listing 9-4 
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quiet run 

linker 8-14 


R 


R 

MEMORY attribute 8-21 
RAM model of autoinitialization 8-11, 
8-51 

recursive macros 6-22 
register 

aliasing 3-10 

relocatable output module 8-10 
relocatable symbols 3-20 
relocation 2-14, 3-23, 8-10 
relocation information A-10 
reserved words 
linker 8-18 

ROM model of autoinitialization 8-11, 
8-51 

rom370 command 10-9 
rts.lib 8-51, 8-52 

Rule 1, output sections contents 8-40 
Rule 2, output sections contents 8-40 
run 

linker keyword 8-31 
run (linker keyword) 2-15 
runtime initialization 8-51 
runtime support 8-51 


S 


section headers A-8 
section specifications 8-23 
SECTIONS 

linker directive 8-23 
alignment 8-28 
allocation 8-23, 8-25, 8-26 
binding 8-26 
blocking 8-28 
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default allocation 8-39 
default model 8-23 
GROUP 8-38 
named memory 8-27 
overlay pages 8-39 
reserved words 8-18 
section specifications 8-23 
specifying runtime address 8-31 
specifying two addresses 8-31 
syntax 8-23 
UNION 8-35 

use with MEMORY directive 8-22 
specifying runtime address 2-15 
specifying two addresses 2-15 
sections 

special section types 8-41 
SECTIONS (linker directive) 2-11 
software installation 
IBM PC/AT 1-6 

list of supported operating systems 
1-6 

PC-DOS, MS-DOS, or OS/2 1-6 
UNIX 1-7 
VAX/VMS 1-7 
software stack 

default size 8-15 
source listings 3-23, 3-25 
source statement 

field (source listing) 3-23 
format - 3-9, 3-10,3-11 
comment field 3-11 
label field 3-9 
mnemonic field 3-9 
operand field 3-9 
number (source listing) 3-23 
SPC 2-8 
aligning 

by creating a hole 8-46 
linker 8-43 

to byte boundaries 4-20 
assembler's effect on 2-8 
assigning a label to 3-9 
linker symbol 8-42, 8-45 
maximum number of 2-8 
value associated with labels 3-9 
value shown in source listings 3-23 
special section types 8-41 
special symbols in the symbol table A-16 
sstack (-sstack) 


linker 8-15 

SSTACK_SIZE (__SSTACK_SIZE) 8-45 
stack size 
linker 8-15 
static variables A-14 
storage classes A-19 
string . . . 

functions (substitution symbols) 

$firstch 6-10 
$iscons 6-10 
$isdefed 6-10 
$ismember 6-10 
$isname 6-10 
$isreg 6-10 
$lastch 6-10 
$symcmp 6-10 
$symlen 6-10 
string table A-18 
stripping line number entries 8-15 
stripping symbolic information 8-15 
structure definitions B-10 
structure tag (.stag) 4-61 
structure tag (stag) 4-17 
substitution symbols 6-4, 6-7 
-var (macro directive) 6-14 
arithmetic operations on 4-17, 4-21, 
6-9 

as local variables in macros 6-14 
assigning character strings to 4-17, 
4-21 

builtjn functions 6-9 
directives that define 6-8 
expansion 4-59 
listing 4-14, 4-59 
forcing substitution 6-11 
in macros 6-7 

maximum number per macro 6-7 
passing commas and semicolons 6-7 
recursive substitution 6-11 
subscripted substitution 6-12 
valid definition 6-7 
symbol 

table 2-17 

creating entries 2-17 
symbol names A-17 
symbol table 

entry from .sym directive B-12 
special symbols used in A-16 
stripping entries 8-15 
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structure and content A-14 
symbolic debugging A-12, A~14, B-4 
block definitions B-4 
enumeration definitions B-10 
file identification B-5 
function definitions B-6 
line number entries B-8 
member definitions B-9 
stripping symbolic information 8-15 
structure definitions B-10 
symbol table entries B-12 
union definitions B-10 
symbolic offsets 4-61 
symbols 2-17, 3-15 

and their definitions (cross_reference 
list) 3-3, 3-26 
assigning values to 4-56 
at link time 8-42 
character strings 3-14 
number of statements that reference 
3-26 

relocatable symbols in expressions 
3-20 

reserved words 8-18 
statement number that defines 3-26 
value assigned 3-26 
symbols and abbreviations 5-4 
system stack, C language 8-52 


T 


Tektronix hex object format 10-5 
Tektronix object format 10-3,10-9 
TLtagged object format 10-3, 10-7, 10-9 
TMS370 archiver See archiver 


TMS370 linker See linker 
TMS370 object format converter See 
object format converter 
type entry A-21 
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unconfigured memory 8-20, 8-39 
underflow (in expressions) 3-19 
uninitialized sections 8-45 
holes 8-48 
initializing 8-48 
UNION 

SECTIONS directive 8-35 
union definitions B-10 
UNIX software installation 1-7 
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VAX/VMS software installation 1-7 


W 


w 

MEMORY attribute 8-21 
well._defined expressions 3-20 
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X 

MEMORY attribute 8-21 
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